@sous-io/sous 0.2.11 → 0.2.13

package/docs/markdown/commands.md

@@ -207,7 +207,8 @@ and `git config user.email`), because it commits and cuts annotated tags. Takes
 - `--no-bump`: raise nothing; a changed recipe that was never raised is then an error.
 - `--include-unchanged`: release every recipe in scope, changed or not.
 - `--tag`, `--push`: tag even on a non-default branch, and push the commit and this run's tags.
-- `--check`: only validate, and fail when the committed index is out of date.
+- `--check`: only validate. It fails on a problem the release would refuse, and reports, without failing, how
+  merging would rewrite the committed index.
 - `--ci`: the merge preset. Never bump, never ask, and fail on anything unbumped. It still needs `--yes` to
   accept the plan it prints, so a merge job runs `sous repo release --ci --yes --push`.
 

package/docs/markdown/repositories-authoring.md

@@ -195,8 +195,9 @@ third case is what a merge looks like to continuous integration: the bump is don
 
 `--namespace <ns>` and `--recipe <ns/name>` narrow the run and both repeat; `--bump <level>` is `patch` (the
 default), `minor`, `major` or `prerelease`; `--no-bump` raises nothing; `--include-unchanged` releases every
-recipe in scope, changed or not; `--check` only reads, validating and failing when the committed index is stale;
-and `--ci` is the merge preset: never bump, accept the plan, never ask, fail on anything unbumped. Every flag
+recipe in scope, changed or not; `--check` only reads, validating, failing on any problem the release would
+refuse, and reporting how merging would rewrite the committed index without failing on it, since that index is
+the release's output; and `--ci` is the merge preset: never bump, accept the plan, never ask, fail on anything unbumped. Every flag
 this command takes, `--tag`, `--push` and `--non-interactive` among them, is in the
 [command reference](commands.md#sous-repo-release).
 
@@ -244,7 +245,8 @@ give that identity to the account a continuous integration job runs as (the scaf
 `sous repo init` writes `.github/workflows/sous-release.yml`, which runs the same command in its two presets,
 calling the CLI from npm so nothing is installed into the repository. On a **pull request** it runs
 `npx --yes @sous-io/sous repo release --check`, which only reads, so it is safe on an untrusted branch and
-fails the pull request when a manifest is wrong or the committed index is stale. On a **push to `main`** it
+fails the pull request when a manifest is wrong or a published version changed, and notes how the merge will
+rewrite the index. On a **push to `main`** it
 runs `npx --yes @sous-io/sous repo release --ci --push --yes`; edit the workflow's `branches` list if your
 default branch has another name. `--ci` accepts the plan on its own, the redundant `--yes` keeping the file
 working with an older published sous. Both jobs check out with `fetch-depth: 0`, so existing tags are visible
@@ -295,8 +297,13 @@ printing each step:
 
 1. **Preflight.** An `origin` remote exists, sous recognizes its provider, that provider's command line tool
    (`gh` or `glab`) is installed and signed in, and everything is committed.
-2. **Validation.** The repository validates and the committed index is current, so a proposal never fails the
-   maintainer's own checks and wastes their review.
+2. **Validation.** The repository validates, and your change leaves `sous.index.json` as it found it, so a
+   proposal never fails the maintainer's own checks and wastes their review. The index is written by the
+   repository's own release after a merge; whether it agrees with the release tags is checked there, by
+   `sous repo release --check` on a full clone, not by `submit`. That is what lets `submit` run from the shallow
+   checkout `sous repo link` makes, which holds almost none of the tags. The comparison is made against the
+   copy of the default branch your checkout holds (`origin/main`, for example); when it holds none, `submit`
+   says the check was skipped.
 3. **Delegation.** Sous asks the provider whether you can push to the repository itself, forks it onto your
    account when you cannot, pushes the branch, and asks the provider to open the proposal. A change sitting on
    the default branch is moved to `sous/submit-<YYYYMMDD>-<HHMM>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.11
+version: 0.2.13
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/commands/repo/release.ts

@@ -40,12 +40,15 @@ import {
   type ValidationProblem,
 } from "../../lib/repos/release/index.js";
 import {
+  BULLET,
   blankLine,
   displayErrorBlock,
   dryRunNotice,
   footer,
   header,
   log,
+  note,
+  paragraph,
   section,
   showCommandVars,
   showVariables,
@@ -373,23 +376,22 @@ export default class RepoRelease extends Command {
     reportProblems(result.problems);
     if (hasErrors(result.problems)) return this.stopForErrors(result.problems);
 
-    if (!result.stale) {
+    // The index is the release's output, not the author's: the release that
+    // runs after a merge rewrites it before tagging. So drift here is reported
+    // as what merging will change, never as a failure; only the problems the
+    // index build raises above stop a check.
+    if (result.stale) {
+      note(`Merging rewrites the committed ${INDEX_FILENAME}, because:`);
+      for (const line of describeIndexDrift(existing, result.index)) {
+        paragraph(`${BULLET} ${line}`, { indent: 4, hangingIndent: 2 });
+      }
+      blankLine();
+    } else {
       log(`  The committed ${INDEX_FILENAME} is current, and so are the dependencies it`);
       log("  records for every version it publishes.");
-      reportPending(result, "These versions have no tag yet; they publish when this merges:");
-      footer();
-      return;
     }
-
-    const lines = [
-      `The committed ${INDEX_FILENAME} is out of date:`,
-      "",
-      ...describeIndexDrift(existing, result.index).map((line) => `  ${line}`),
-      "",
-      "Run 'sous repo release' to regenerate it, and commit what it writes.",
-    ];
-    displayErrorBlock(lines.join("\n"));
-    this.exit(1);
+    reportPending(result, "These versions have no tag yet; they publish when this merges:");
+    footer();
   }
 
   // --- Output ---------------------------------------------------------------------------------

package/src/commands/repo/submit.ts

@@ -1,5 +1,4 @@
 import { Command, Flags } from "@oclif/core";
-import { SOUS_VERSION } from "../../lib/settings.js";
 import { findRepoRoot, submitRepo } from "../../lib/repos/release/index.js";
 import { reportCommandError } from "../../utils/command-errors.js";
 import { nonInteractiveFlag } from "../../utils/flags.js";
@@ -90,7 +89,6 @@ export default class RepoSubmit extends Command {
       body: flags.body,
       draft: flags.draft,
       dryRun,
-      sousVersion: SOUS_VERSION,
       onStep: (message) => log(`  ${message}`),
       onNotice: (message) => (dryRun ? dryRunNotice(message) : log(`  ${message}`)),
     });

package/src/lib/repos/release/git-state.ts

@@ -105,6 +105,59 @@ export async function defaultBranch(
   }
 }
 
+/**
+ * The commit where this checkout's own work starts: the point HEAD shares with
+ * the remote's copy of a branch. Returns undefined when this checkout holds no
+ * copy of that branch, or when git cannot find a commit the two share.
+ *
+ * A shallow clone answers this as long as HEAD was built on the branch it was
+ * cloned from, which is why a submission can rely on it where it cannot rely on
+ * tags.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param remote - The remote whose branch is compared, normally `origin`.
+ * @param branch - The branch on that remote, normally the default one.
+ * @param options - The command runner to use.
+ */
+export async function forkPoint(
+  rootDir: string,
+  remote: string,
+  branch: string,
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  try {
+    const commit = await runGit(["merge-base", `refs/remotes/${remote}/${branch}`, "HEAD"], {
+      cwd: rootDir,
+      run: options.run,
+    });
+    return commit.length > 0 ? commit : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * True when the commits since `since` changed a path, comparing that commit
+ * with HEAD.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param since - The commit to compare HEAD with.
+ * @param relativePath - The path to check, relative to the repository root.
+ * @param options - The command runner to use.
+ */
+export async function pathChangedSince(
+  rootDir: string,
+  since: string,
+  relativePath: string,
+  options: RunOptions = {}
+): Promise<boolean> {
+  const changed = await runGit(["diff", "--name-only", since, "HEAD", "--", relativePath], {
+    cwd: rootDir,
+    run: options.run,
+  });
+  return changed.length > 0;
+}
+
 /**
  * The URL of a remote, or undefined when the repository has no such remote.
  *

package/src/lib/repos/release/submit-service.ts

@@ -15,8 +15,12 @@
  *
  * Two rules shape everything here:
  *
- * - Nothing is sent until the repository validates and its index is current. A
- *   proposal that fails the maintainer's own checks wastes their review.
+ * - Nothing is sent until the repository validates and the contributor has left
+ *   its index alone. A proposal that fails the maintainer's own checks wastes
+ *   their review. Whether the index agrees with the tags is the maintainer's
+ *   check, not the contributor's: `sous repo release --check` makes it on a full
+ *   clone, while a contributor usually works in the shallow checkout that
+ *   `sous repo link` makes, which holds almost none of the tags.
  * - Every step announces itself BEFORE it runs, and a failure says exactly which
  *   steps completed. A half-finished submission (a branch pushed, no proposal
  *   opened) is a normal outcome of a network failure, and the contributor has to
@@ -36,17 +40,16 @@ import {
   type RepoProvider,
   type SubmitCapableProvider,
 } from "../providers/provider.js";
-import {
-  buildIndex,
-  describeIndexDrift,
-  readIndexFile,
-  type IndexBuildResult,
-} from "./index-builder.js";
+import { INDEX_FILENAME } from "../formats/common.js";
+import type { IndexFile } from "../formats/index-file.js";
+import { readIndexFile } from "./index-builder.js";
 import {
   currentBranch,
   createBranch,
   defaultBranch,
+  forkPoint,
   lastCommitSubject,
+  pathChangedSince,
   pushBranch,
   remoteUrl,
   submitBranchName,
@@ -81,8 +84,6 @@ export type SubmitOptions = {
   draft?: boolean;
   /** When true, everything is checked and reported and nothing is sent. */
   dryRun?: boolean;
-  /** The version of sous, recorded when the index is regenerated for the check. */
-  sousVersion: string;
   /** When the submission is happening; decides the branch name. Defaults to now. */
   now?: Date;
   /** How subprocesses are run. Defaults to spawning a real process. */
@@ -127,7 +128,6 @@ export type SubmitResult = {
 export async function submitRepo(options: SubmitOptions): Promise<SubmitResult> {
   const {
     rootDir,
-    sousVersion,
     draft = false,
     dryRun = false,
     now = new Date(),
@@ -204,19 +204,27 @@ export async function submitRepo(options: SubmitOptions): Promise<SubmitResult>
   assertRepoValidates(validation);
   completed.push("Checked that every recipe describes itself correctly");
 
-  step("Confirming the committed index is current");
-  const built = await buildIndex({
-    validation,
-    existing: readIndexFile(rootDir),
-    sousVersion,
-    run,
-  });
-  assertIndexReady(built, readIndexFile(rootDir));
-  completed.push("Confirmed the committed index is current");
+  const baseBranch = (await defaultBranch(rootDir, { run })) ?? "main";
+
+  step(`Checking that ${INDEX_FILENAME} was left alone`);
+  const since = await forkPoint(rootDir, UPSTREAM_REMOTE, baseBranch, { run });
+  if (since === undefined) {
+    notice(
+      `This checkout holds no copy of '${UPSTREAM_REMOTE}/${baseBranch}', so sous could not ` +
+        `check whether ${INDEX_FILENAME} was changed.`
+    );
+  } else if (await pathChangedSince(rootDir, since, INDEX_FILENAME, { run })) {
+    throw new ConfigError(
+      `This change edits ${INDEX_FILENAME}. The index is written by the repository's own ` +
+        `release, after a change is merged, so a proposal leaves it as it found it.\n` +
+        `  Restore it with 'git checkout ${since.slice(0, 12)} -- ${INDEX_FILENAME}', ` +
+        `commit that, then run the command again.`
+    );
+  }
+  completed.push(`Checked that ${INDEX_FILENAME} was left alone`);
 
   // --- The branch the change lives on ---------------------------------------
 
-  const baseBranch = (await defaultBranch(rootDir, { run })) ?? "main";
   const checkedOut = await currentBranch(rootDir, { run });
   let branch = checkedOut;
 
@@ -233,7 +241,7 @@ export async function submitRepo(options: SubmitOptions): Promise<SubmitResult>
 
   const title =
     options.title ?? (await lastCommitSubject(rootDir, { run })) ?? defaultTitle(validation);
-  const body = options.body ?? defaultBody(built, validation);
+  const body = options.body ?? defaultBody(validation, readIndexFile(rootDir));
 
   // --- Fork, push, propose --------------------------------------------------
 
@@ -332,34 +340,6 @@ function assertRepoValidates(validation: RepoValidation): void {
   );
 }
 
-/** Refuses to submit while the index disagrees with what the repository publishes. */
-function assertIndexReady(
-  built: IndexBuildResult,
-  existing: ReturnType<typeof readIndexFile>
-): void {
-  if (hasErrors(built.problems)) {
-    throw new ConfigError(
-      "This repository's index and its tags do not agree, so there is nothing worth " +
-        "proposing yet:\n\n" +
-        renderProblems(errorsIn(built.problems)) +
-        "\n\n  Fix these, then run the command again."
-    );
-  }
-
-  if (built.stale) {
-    const drift = describeIndexDrift(existing, built.index)
-      .map((line) => `    ${line}`)
-      .join("\n");
-    throw new ConfigError(
-      "The committed index is out of date, and a maintainer's own checks would reject " +
-        "the proposal:\n\n" +
-        `${drift}\n\n` +
-        "  Run 'sous repo release', commit the regenerated index, then run this command " +
-        "again."
-    );
-  }
-}
-
 /** Renders a list of problems as an indented block. */
 function renderProblems(problems: ReadonlyArray<ValidationProblem>): string {
   return problems.map((problem) => `    ${problem.where}: ${problem.message}`).join("\n");
@@ -450,8 +430,22 @@ function defaultTitle(validation: RepoValidation): string {
   return `Update the ${validation.manifest.name} recipes`;
 }
 
+/**
+ * The versions merging this change would publish: every recipe whose manifest
+ * declares a version the committed index does not list yet. Worked out from
+ * the manifests and the index alone, so it needs none of the tags.
+ */
+function versionsToPublish(
+  validation: RepoValidation,
+  index: IndexFile | undefined
+): Array<{ key: string; version: string }> {
+  return validation.recipes
+    .filter((recipe) => index?.recipes[recipe.key]?.versions[recipe.manifest.version] === undefined)
+    .map((recipe) => ({ key: recipe.key, version: recipe.manifest.version }));
+}
+
 /** The body sous writes when the contributor did not supply one. */
-function defaultBody(built: IndexBuildResult, validation: RepoValidation): string {
+function defaultBody(validation: RepoValidation, index: IndexFile | undefined): string {
   const lines = [
     `Proposed with 'sous repo submit' from the ${validation.manifest.name} repository.`,
     "",
@@ -460,10 +454,11 @@ function defaultBody(built: IndexBuildResult, validation: RepoValidation): strin
   for (const recipe of validation.recipes) {
     lines.push(`- ${recipe.key} at version ${recipe.manifest.version}`);
   }
-  if (built.pending.length > 0) {
+  const toPublish = versionsToPublish(validation, index);
+  if (toPublish.length > 0) {
     lines.push("");
     lines.push("Versions this proposal would publish once it is merged and tagged:");
-    for (const entry of built.pending) {
+    for (const entry of toPublish) {
       lines.push(`- ${entry.key} ${entry.version}`);
     }
   }

package/src/lib/repos/scaffold/templates.ts

@@ -327,10 +327,10 @@ export function buildReleaseWorkflow(): string {
 # installed into this repository:
 #
 #   'sous repo release --check' validates every manifest, confirms each recipe
-#   folder matches what the repo manifest lists, and confirms the committed
-#   index agrees with the versions and dependencies the recipe manifests
-#   declare. It only reads; it never writes, commits or tags. That makes it the
-#   right thing to run on a pull request.
+#   folder matches what the repo manifest lists, and reports how merging would
+#   rewrite the committed index, which the release after a merge regenerates.
+#   It only reads; it never writes, commits or tags. That makes it the right
+#   thing to run on a pull request.
 #
 #   'sous repo release --ci --push --yes' does the same validation and then
 #   publishes. '--ci' raises no versions, accepts the plan it prints, and asks