@savvy-web/silk-effects 7.5.3 → 8.0.0

package/pr-body/markers.js

@@ -1,103 +0,0 @@
-import { Region } from "./region.js";
-
-//#region src/pr-body/markers.ts
-/**
-* The frozen `silk-release` marker vocabulary — the wire format of the shared
-* PR-body contract.
-*
-* @remarks
-* **The `silk-release:` token is frozen and names the CONTRACT, not the
-* emitting action.** `silk-update-action` PRs carry the same markers as
-* release PRs, deliberately: every live document, the `pr-body` plugin skill,
-* and every agent that edits a managed PR description key on these exact
-* byte sequences. Do not parameterize the token per action and do not rename
-* it — either forks the wire format for zero gain and orphans every open PR
-* (ruled in savvy-web/systems#419).
-*
-* These constants are the single source of truth for the marker grammar.
-* The agent-facing documentation in the silk plugin (`pr-body` and
-* `commit-create` skills) duplicates the literals for readability; a drift
-* lint in this package's test suite asserts the copies stay in sync.
-*/
-/**
-* The marker constants of the `silk-release` PR-body contract.
-*
-* @public
-*/
-var Markers = class {
-	constructor() {}
-	/**
-	* Opening marker of the whole managed region.
-	*
-	* @remarks
-	* Everything between this and {@link Markers.MANAGED_END} that is not
-	* inside the summary or references region is regenerated wholesale on
-	* every run; everything outside the pair is human territory and survives
-	* every regeneration.
-	*
-	* @public
-	*/
-	static MANAGED_START = Region.start("silk-release");
-	/**
-	* Closing marker of the whole managed region.
-	*
-	* @public
-	*/
-	static MANAGED_END = Region.end("silk-release");
-	/**
-	* Opening marker of the region an AI summariser owns.
-	*
-	* @remarks
-	* The generating action never writes into this region — it only reserves
-	* it and carries its content through on regeneration.
-	*
-	* @public
-	*/
-	static SUMMARY_START = Region.start("silk-release:summary");
-	/**
-	* Closing marker of the summariser's region.
-	*
-	* @public
-	*/
-	static SUMMARY_END = Region.end("silk-release:summary");
-	/**
-	* The PLAIN opening marker of the closing-reference region — the form an
-	* author writes by hand.
-	*
-	* @remarks
-	* A generating run emits the ATTRIBUTED form instead (the plain prefix
-	* plus an `owned="…"` attribute). Never locate the region by matching
-	* this constant — match {@link Markers.REFERENCES_START_PREFIX}, or a
-	* region a run wrote will not be found.
-	*
-	* @public
-	*/
-	static REFERENCES_START = Region.start("silk-release:references");
-	/**
-	* Closing marker of the closing-reference region.
-	*
-	* @public
-	*/
-	static REFERENCES_END = Region.end("silk-release:references");
-	/**
-	* The references opening marker up to its attributes, for locating a
-	* region whose `owned` list is unknown.
-	*
-	* @public
-	*/
-	static REFERENCES_START_PREFIX = "<!-- silk-release:references:start";
-	/**
-	* The fence language for the proposed squash-commit block.
-	*
-	* @remarks
-	* Not a GFM language and apparently undocumented, but GitHub renders it.
-	* It is a target for AI integrations to read and rewrite into the
-	* eventual squash-commit message. **Do not "correct" it to `text`.**
-	*
-	* @public
-	*/
-	static SQUASH_FENCE_LANGUAGE = "proposed-squash-commit";
-};
-
-//#endregion
-export { Markers };

package/pr-body/references.js

@@ -1,157 +0,0 @@
-import { Markers } from "./markers.js";
-import { LinkedIssueRef } from "./linked-issue.js";
-import { Schema } from "effect";
-import { parseBareLines } from "@effected/github-references";
-
-//#region src/pr-body/references.ts
-/**
-* An ordered list of issue ids destined for closing references, with the two
-* renderers whose difference is the whole point of this module.
-*
-* @remarks
-* The same issues appear twice in a managed PR body, spelled differently, and
-* **neither consumer accepts the other's spelling**:
-*
-* - commitlint reads ONE comma-joined trailer (`Closes #1, #2`) inside the
-*   proposed-squash-commit fence — {@link ClosingReferences.renderTrailer};
-* - GitHub's linker reads one bare `Closes #N` line each, OUTSIDE every
-*   fence — {@link ClosingReferences.renderBareLines}. A reference inside a
-*   fenced block is inert to GitHub.
-*
-* The duplication is load-bearing. Never "simplify" a body by emitting one
-* form in both places: comma-joined bare lines link nothing (verified by hand
-* against live pull requests — `savvy-web/silk-integration` #242/#232 with no
-* bare line reported `closingIssuesReferences: []`, #243 with one reported
-* `[168]`), and per-line trailers inside the fence break the commit contract.
-*
-* Ids are stored exactly as given — construction neither deduplicates nor
-* sorts. Call {@link ClosingReferences.dedupe} where uniqueness is wanted;
-* the split exists because the squash trailer historically renders duplicates
-* as-given while the references region deduplicates, and byte-compatibility
-* with live PR bodies pins that behavior.
-*
-* @public
-*/
-var ClosingReferences = class ClosingReferences extends Schema.Class("ClosingReferences")({ ids: Schema.Array(Schema.Number.check(Schema.isInt())) }) {
-	/**
-	* The open issues' ids, in input order, duplicates preserved.
-	*
-	* @remarks
-	* Closedness is decided by `LinkedIssueRef.isClosed` — the only
-	* sanctioned test, case-insensitive so REST (`closed`) and GraphQL
-	* (`CLOSED`) payloads classify identically.
-	*
-	* @public
-	*/
-	static fromIssues(issues) {
-		return ClosingReferences.make({ ids: issues.filter((issue) => !LinkedIssueRef.isClosed(issue)).map((issue) => issue.number) });
-	}
-	/**
-	* Issue ids carried by a region's bare closing lines.
-	*
-	* @remarks
-	* The region is read with `@effected/github-references`' `parseBareLines`
-	* — per line, the whole line, after trimming, must be
-	* `<keyword>[:] #<number>`, so a number mentioned in passing is never
-	* mistaken for a closing reference. Every keyword GitHub accepts counts,
-	* not just the present-tense plural this contract emits, because a
-	* reference the parser fails to recognise is one the next regeneration
-	* silently deletes.
-	*
-	* @public
-	*/
-	static parseBare(region) {
-		return parseBareLines(region).map((ref) => ref.issueNumber);
-	}
-	/**
-	* A copy with duplicate ids removed, first occurrence winning.
-	*
-	* @public
-	*/
-	dedupe() {
-		return ClosingReferences.make({ ids: [...new Set(this.ids)] });
-	}
-	/**
-	* The comma-joined trailer the squash-commit message carries, or `""`
-	* when there is nothing to close.
-	*
-	* @remarks
-	* `Closes #1, #2` on ONE line — the spelling commitlint reads and
-	* GitHub's linker ignores. See the class remarks before changing either
-	* renderer.
-	*
-	* @public
-	*/
-	renderTrailer() {
-		if (this.ids.length === 0) return "";
-		return `Closes ${this.ids.map((id) => `#${id}`).join(", ")}`;
-	}
-	/**
-	* One bare `Closes #N` line per id, or `""` when empty.
-	*
-	* @remarks
-	* The spelling GitHub's linker reads — each line must sit OUTSIDE every
-	* fenced block to link. See the class remarks before changing either
-	* renderer.
-	*
-	* @public
-	*/
-	renderBareLines() {
-		return this.ids.map((id) => `Closes #${id}`).join("\n");
-	}
-};
-/**
-* The `owned="…"` attribute on the references region's opening marker.
-*
-* @remarks
-* Records the issue ids a generating run emitted itself, so the next run can
-* tell its own references from ones an agent or human added. "Not in this
-* run's linked set" is NOT enough: a reference the previous run emitted also
-* disappears from the linked set when the release stops tracking that issue,
-* and treating it as agent-authored would preserve it forever — re-linking,
-* and on merge auto-closing, an issue the release deliberately dropped.
-*
-* **Never hand-edit the attribute.** A wrong value makes the next run delete
-* a real reference or resurrect a dropped one.
-*
-* @public
-*/
-var OwnedAttribute = class {
-	constructor() {}
-	/**
-	* The attribute as emitted on the opening marker.
-	*
-	* @public
-	*/
-	static render(ids) {
-		return `owned="${ids.join(",")}"`;
-	}
-	/**
-	* The ids the prior body's opening marker claims as the previous run's
-	* own.
-	*
-	* @remarks
-	* An absent or malformed attribute reads as "none", which degrades to
-	* treating every reference in the region as agent-authored. That
-	* preserves too much rather than deleting someone's work — the safe
-	* direction to fail. The match is anchored to an attribute boundary: an
-	* unanchored match also finds `data-owned="…"` and `unowned="…"`, which
-	* would let an unrelated attribute claim an agent's reference and get it
-	* dropped on the next run.
-	*
-	* @public
-	*/
-	static parse(priorBody) {
-		const from = priorBody.indexOf(Markers.REFERENCES_START_PREFIX);
-		if (from === -1) return /* @__PURE__ */ new Set();
-		const openEnd = priorBody.indexOf("-->", from);
-		if (openEnd === -1) return /* @__PURE__ */ new Set();
-		const attributes = priorBody.slice(from + Markers.REFERENCES_START_PREFIX.length, openEnd);
-		const owned = /(?:^|\s)owned="([\d,\s]*)"/.exec(attributes)?.[1];
-		if (owned === void 0) return /* @__PURE__ */ new Set();
-		return new Set(owned.split(",").map((part) => part.trim()).filter((part) => part !== "").map(Number));
-	}
-};
-
-//#endregion
-export { ClosingReferences, OwnedAttribute };

package/pr-body/region.js

@@ -1,105 +0,0 @@
-//#region src/pr-body/region.ts
-/**
-* The generic marker-delimited region grammar every silk-managed document
-* uses: `<!-- token:start -->` … `<!-- token:end -->`.
-*
-* @remarks
-* Extracted from `silk-release-action` (its `pr-body.ts` and
-* `managed-sections.ts` both carried a private copy) so the grammar has one
-* owner. **Every marker is a pair.** A lone opening marker can only be located
-* by scanning forward to whatever happens to follow it, which makes the
-* region's extent a function of its neighbours rather than of itself — moving
-* anything nearby silently redefines it. The token is free-form; `:start` and
-* `:end` are the whole contract, so pairs nest and a region can contain
-* sub-regions without either needing to know about the other.
-*/
-/**
-* Pure helpers over the `<!-- token:start -->` / `<!-- token:end -->` region
-* grammar.
-*
-* @remarks
-* Every operation is total: a body with no region (or a broken pair) degrades
-* to the documented fail-safe result rather than failing, because the callers
-* are regenerating actions that must still produce a body when the prior one
-* is malformed. Use `PrBodyDiagnostic.scan` when a caller wants to be told
-* about a broken pair instead of silently tolerating it.
-*
-* @public
-*/
-var Region = class Region {
-	constructor() {}
-	/**
-	* The opening delimiter for a named region.
-	*
-	* @public
-	*/
-	static start(token) {
-		return `<!-- ${token}:start -->`;
-	}
-	/**
-	* The closing delimiter for a named region.
-	*
-	* @public
-	*/
-	static end(token) {
-		return `<!-- ${token}:end -->`;
-	}
-	/**
-	* The content between a region's delimiters, or `undefined` when absent.
-	*
-	* @remarks
-	* Finds the FIRST opening marker and the matching close after it, so a
-	* nested region of a different token is returned as part of the content
-	* rather than truncating it.
-	*
-	* @public
-	*/
-	static read(body, token) {
-		const from = body.indexOf(Region.start(token));
-		const to = body.indexOf(Region.end(token), from === -1 ? 0 : from);
-		if (from === -1 || to === -1 || to < from) return void 0;
-		return body.slice(from + Region.start(token).length, to);
-	}
-	/**
-	* Everything outside a region, with the region and its delimiters removed.
-	*
-	* @remarks
-	* A body without the region comes back unchanged — removal of an absent
-	* region is a no-op, not an error.
-	*
-	* @public
-	*/
-	static strip(body, token) {
-		const from = body.indexOf(Region.start(token));
-		const to = body.indexOf(Region.end(token), from === -1 ? 0 : from);
-		if (from === -1 || to === -1 || to < from) return body;
-		return `${body.slice(0, from)}${body.slice(to + Region.end(token).length)}`;
-	}
-	/**
-	* Put `rendered` (a fully rendered region, its own markers included) into
-	* `body`, replacing a previous region of the same token and leaving
-	* everything else alone.
-	*
-	* @remarks
-	* **Human edits outside the markers survive.** A predecessor spliced on a
-	* markdown heading, which silently ate any content a human happened to put
-	* under a heading of that name and could not tell generated text from
-	* theirs. An explicit marker pair can.
-	*
-	* A body with no markers keeps its content and gains the region **below**
-	* it, so an existing hand-written document is not displaced. The result is
-	* trimmed.
-	*
-	* @public
-	*/
-	static upsert(body, token, rendered) {
-		const start = body.indexOf(Region.start(token));
-		const end = body.indexOf(Region.end(token));
-		if (start !== -1 && end !== -1 && end > start) return `${body.slice(0, start)}${rendered}${body.slice(end + Region.end(token).length)}`.trim();
-		const trimmed = body.trim();
-		return trimmed === "" ? rendered : `${trimmed}\n\n${rendered}`;
-	}
-};
-
-//#endregion
-export { Region };

package/schemas/SavvyInstallSection.js

@@ -1,232 +0,0 @@
-import { CommentStyle, SectionId } from "@effected/templates";
-
-//#region src/schemas/SavvyInstallSection.ts
-/**
-* Section identity for the dependency auto-install block.
-*
-* `toolName` is `"savvy-install"`; pair with {@link savvyInstallDeps}.
-*
-* @since 7.5.0
-* @public
-*/
-const SavvyInstallSection = SectionId.make({
-	key: "SAVVY-INSTALL",
-	commentStyle: CommentStyle.hash
-});
-/**
-* Pathspecs whose change across a checkout or merge means `node_modules` is stale.
-*
-* @remarks
-* Git's default pathspec globbing does not stop a wildcard at a slash, so the
-* one nested-manifest entry below covers every workspace manifest at any depth
-* without needing a recursive spelling. Manifests are listed alongside lockfiles
-* because a dependency edit that has not been installed yet moves the manifest
-* first and the lockfile not at all.
-*/
-const DEPENDENCY_PATHS = [
-	"package.json",
-	"*/package.json",
-	"pnpm-lock.yaml",
-	"pnpm-workspace.yaml",
-	"package-lock.json",
-	"npm-shrinkwrap.json",
-	"yarn.lock",
-	"bun.lock",
-	"bun.lockb"
-].map((path) => `'${path}'`).join(" ");
-/**
-* Dependency auto-install shared across Silk Suite hook files.
-*
-* @remarks
-* Brings `node_modules` back in line after a branch switch or a pull, so a batch
-* of repos pulled to align their dependencies does not each need a manual
-* install. Installs with lifecycle scripts skipped — `--ignore-scripts`, or
-* `--mode=skip-build` for Yarn Berry, which dropped the former — because the goal
-* is to get the dependency tree on disk, not to run a full postinstall.
-*
-* **That flag has a cost, and one shape of repo cannot pay it.** Where a package
-* publishes through a built link directory — `publishConfig.directory` with
-* `linkDirectory: true`, which is how this monorepo wires `dist/dev/pkg` — the
-* workspace resolves its own dependencies through a directory that a `prepare`
-* script has to build, and skipping scripts yields a populated `node_modules`
-* pointing at nothing.
-*
-* Those repos ask for a full install through the LOCAL git config key
-* `savvy.installLifecycleScripts`, which `savvy init` sets when it finds the
-* shape. The decision deliberately does NOT read the checked-out tree. Doing so
-* failed in both directions at once: a branch that merely declared the shape
-* could turn lifecycle scripts back on just by being checked out, making
-* `git checkout` of an untrusted revision a code-execution path; and the `jq`
-* the scan needed is absent on stock macOS and Ubuntu, where the missing answer
-* silently skipped scripts in precisely the repos that cannot survive it.
-* `.git/config` is neither checked out nor parsed with `jq`, so it has neither
-* failure mode.
-*
-* The package managers gate dependency scripts themselves on top of this —
-* pnpm's `strictDepBuilds` with an `allowBuilds` allowlist being the case in
-* point — but workspace and root lifecycle scripts still run, which is why the
-* opt-in is local rather than inferred. With the flag on, the hook says on the
-* way out that scripts were skipped rather than leaving it to be discovered.
-*
-* Deliberately self-contained, like `savvyToolchainCheck`: its homes carry
-* `SavvyHooksSection` but no `SavvyBaseSection`, so it defines its own root, CI
-* and package-manager lookups rather than depending on `ROOT`, `in_ci` or `PM`.
-*
-* Four guards keep it from firing on the many checkouts that are not dependency
-* events, each a silent no-op:
-*
-* - CI, where the runtime action owns installation by construction.
-* - `SAVVY_SKIP_INSTALL`, the escape hatch for a bisect or a scripted sweep that
-*   does not want an install between steps.
-* - `post-checkout` only: a branch-flag of `0`, which is `git checkout -- <file>`
-*   and not a move between commits.
-* - **The gate that makes this affordable:** nothing dependency-related actually
-*   changed across the move. Without it every branch switch would pay for a full
-*   install. A missing `node_modules` overrides it, since there is nothing to be
-*   stale.
-*
-* A fresh clone is not among the cases it handles, and cannot be: husky sets
-* `core.hooksPath` from its own `prepare` script, so until the first manual
-* install has run there is no hook installed to fire.
-*
-* The install's exit status is swallowed and its output goes to stderr. Git
-* ignores what `post-checkout` and `post-merge` return, so a failure here must
-* not look like a failed checkout; the hint names the escape hatch instead.
-*
-* Every probe that can legitimately fail — no `ORIG_HEAD` to compare against, an
-* unresolvable range — is neutralised with `|| true` rather than left to its own
-* status. These blocks are co-owned and consumer content can sit below them, so
-* under a hook running `set -e` a bare failing substitution would abort the whole
-* file and take those later sections with it.
-*
-* @param hook - Which hook the block is being generated for; decides the
-*   argument guard and how the comparison range is recovered.
-* @returns The install shell, with no surrounding markers or trailing newline.
-*
-* @since 7.5.0
-* @public
-*/
-function savvyInstallDeps(hook) {
-	const skip = `! { [ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ] || [ -n "$SAVVY_SKIP_INSTALL" ]; }`;
-	return `if ${hook === "post-checkout" ? `${skip} && [ "$3" = "1" ]` : skip}; then
-  install_root=$(git rev-parse --show-toplevel 2>/dev/null) || true
-${hook === "post-checkout" ? `  install_from="$1"
-  install_to="$2"` : `  install_from=$(git rev-parse --verify --quiet ORIG_HEAD 2>/dev/null) || true
-  install_to="HEAD"`}
-  install_pm=""
-  if [ -n "$install_root" ] && [ -f "$install_root/package.json" ]; then
-    if command -v jq >/dev/null 2>&1; then
-      install_pm=$(jq -r '.packageManager // empty' "$install_root/package.json" 2>/dev/null | cut -d'@' -f1)
-    fi
-    if [ -z "$install_pm" ]; then
-      if   [ -f "$install_root/pnpm-lock.yaml" ]; then install_pm="pnpm"
-      elif [ -f "$install_root/yarn.lock" ];      then install_pm="yarn"
-      elif [ -f "$install_root/bun.lock" ] || [ -f "$install_root/bun.lockb" ]; then install_pm="bun"
-      else install_pm="npm"; fi
-    fi
-  fi
-  # packageManager comes from the checked-out revision, so it names an executable
-  # the tree controls. 'command -v' proves a binary exists, not that it is a
-  # package manager, so the name is checked against the supported four first.
-  case "$install_pm" in
-    npm|pnpm|yarn|bun) ;;
-    *) install_pm="" ;;
-  esac
-  # Nothing to bring up to date unless a manifest or lockfile actually moved.
-  # A missing node_modules skips the diff outright: there is no tree to be stale.
-  install_stale=""
-  if [ -n "$install_pm" ]; then
-    if [ ! -d "$install_root/node_modules" ]; then
-      install_stale=1
-    elif [ -n "$install_from" ] && [ -n "$install_to" ]; then
-      install_stale=$(git diff --name-only "$install_from" "$install_to" -- ${DEPENDENCY_PATHS} 2>/dev/null | head -n 1) || true
-    fi
-  fi
-  if [ -n "$install_stale" ] && command -v "$install_pm" >/dev/null 2>&1; then
-    # Whether lifecycle scripts run is a LOCAL decision, read from .git/config,
-    # which no checkout can rewrite. Default off. 'savvy init' turns it on for a
-    # workspace that publishes through built link directories, where the links
-    # point at directories a prepare script has to produce.
-    install_scripts=$(git -C "$install_root" config --bool --get savvy.installLifecycleScripts 2>/dev/null) || true
-    if [ "$install_scripts" = "true" ]; then
-      install_flag=""
-    else
-      # Berry dropped --ignore-scripts for the install mode; Classic never knew the
-      # mode. An unreadable major reads as Berry, the likelier of the two today.
-      install_flag="--ignore-scripts"
-      if [ "$install_pm" = "yarn" ]; then
-        case "$(yarn --version 2>/dev/null | cut -d. -f1)" in
-          1) ;;
-          *) install_flag="--mode=skip-build" ;;
-        esac
-      fi
-    fi
-    # ':+' so a full install announces itself as "pnpm install", not "pnpm install ".
-    printf '↻ dependencies changed, running %s install%s\\n' "$install_pm" "\${install_flag:+ $install_flag}" >&2
-    # Unquoted on purpose: empty must expand to NO argument rather than an empty
-    # one. Safe because every value is a static flag literal from this generator.
-    if ( cd "$install_root" && "$install_pm" install $install_flag ) >&2; then
-      if [ -n "$install_flag" ]; then
-        printf '  Lifecycle scripts were skipped. Run a full install if you need build outputs.\\n' >&2
-      fi
-    else
-      printf '⚠ %s install failed; run it yourself to see why.\\n' "$install_pm" >&2
-      printf '  Set SAVVY_SKIP_INSTALL=1 to stop this hook from trying.\\n' >&2
-    fi
-  fi
-  unset install_root install_from install_to install_pm install_stale install_scripts install_flag
-fi`;
-}
-/**
-* The local git config key that authorizes lifecycle scripts during a hook install.
-*
-* @remarks
-* Local scope only. It lives in `.git/config`, which is never checked out, so no
-* incoming revision can set it — that is the whole point of reading the decision
-* from here rather than from a manifest in the tree.
-*
-* @since 7.5.0
-* @public
-*/
-const LIFECYCLE_SCRIPTS_CONFIG_KEY = "savvy.installLifecycleScripts";
-/**
-* Whether `manifest` publishes through a built link directory.
-*
-* @remarks
-* `publishConfig.directory` with `linkDirectory: true` means consumers of this
-* package resolve it through a directory that a `prepare` script has to produce,
-* so an install that skips lifecycle scripts leaves the link pointing at nothing.
-* A workspace containing any such package is one whose owner probably wants
-* {@link LIFECYCLE_SCRIPTS_CONFIG_KEY} set.
-*
-* Reporting the shape is deliberately separate from acting on it: this answers
-* "does this repo need scripts", and a human still decides whether hook-time
-* installs may run them.
-*
-* @param manifest - A parsed `package.json`; any non-object reads as `false`.
-*
-* @since 7.5.0
-* @public
-*/
-function publishesBuiltLinkDirectory(manifest) {
-	if (typeof manifest !== "object" || manifest === null) return false;
-	const { publishConfig } = manifest;
-	if (typeof publishConfig !== "object" || publishConfig === null) return false;
-	const { directory, linkDirectory } = publishConfig;
-	return typeof directory === "string" && directory.length > 0 && linkDirectory === true;
-}
-/**
-* Build the dependency auto-install block for `hook`.
-*
-* @param hook - Which hook the section is destined for.
-* @returns A shell `Section` (`commentStyle: hash`) keyed `SAVVY-INSTALL`.
-*
-* @since 7.5.0
-* @public
-*/
-function savvyInstallBlock(hook) {
-	return SavvyInstallSection.section(savvyInstallDeps(hook));
-}
-
-//#endregion
-export { LIFECYCLE_SCRIPTS_CONFIG_KEY, SavvyInstallSection, publishesBuiltLinkDirectory, savvyInstallBlock, savvyInstallDeps };