simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/hooks/shim.mjs

@@ -0,0 +1,140 @@
+// Generate the POSIX sh hook shim.
+//
+// The shim is intentionally the smallest thing that can work: it resolves the
+// dispatcher and execs it. Everything else lives in Node, where it can be
+// tested. The event name is baked in at generation time rather than derived from
+// `$0`, because a repo may symlink or copy `pre-push` into `pre-commit` and
+// `$0` would then name the wrong hook - a silent way to run the wrong gates.
+//
+// POSIX sh only. ADR-012 dropped Windows, so there is exactly one code path and
+// no `.cmd` shim to keep in sync.
+//
+// Git's own arguments are deliberately not forwarded. `pre-push` passes a remote
+// name and URL, which argv would then misread as command arguments.
+//
+// The resolution block itself is NOT here: it is shared with the CI workflow, which
+// has to find the binary by the same rules or the gate passes locally and cannot
+// start in CI. See src/locate.mjs.
+
+import { renderLocator } from '../locate.mjs';
+import { BIN_ENV, CLI, MANIFEST_FILE } from '../name.mjs';
+
+/** Events the shared dispatcher knows how to run. */
+export const EVENTS = ['pre-commit', 'pre-push'];
+
+/** Directory the shims are written to inside a repo. */
+export const HOOKS_DIR = '.simt-hooks';
+
+/** Name of the git config key that points at the shim directory. */
+export const HOOKS_PATH_KEY = 'core.hooksPath';
+
+export function fileFor(event) {
+  return `${HOOKS_DIR}/${event}`;
+}
+
+/**
+ * @param {string} event one of EVENTS
+ * @returns {string} POSIX sh source, LF-terminated, executable
+ */
+export function renderShim(event) {
+  if (!EVENTS.includes(event)) {
+    throw new Error(`unknown hook event ${event}; known: ${EVENTS.join(', ')}`);
+  }
+  const D = '$';
+  return `#!/bin/sh
+# Generated by simt-dev. Do not edit.
+#
+# Every decision this hook makes is declared in ${MANIFEST_FILE}, so a reviewer reads
+# the gate list in a diff instead of reverse-engineering shell. Reinstall with:
+# ${CLI} hooks install --yes
+#
+# This file only locates the dispatcher and hands over. It resolves in order:
+#   1. ${D}SIMT_DEV_BIN    explicit override, for CI images and odd checkouts
+#   2. node_modules/       the pinned project dependency
+#   3. simt-dev on PATH    a global install
+# If none resolves it REFUSES rather than exiting 0. A hook that cannot verify
+# anything must never report success - that is what teaches authors to reach for
+# --no-verify.
+
+set -eu
+
+ROOT="${D}(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+${renderLocator(`hooks run ${event} --root "${D}ROOT"`, {
+    subject: 'the dispatcher',
+    remedy: `REMEDY set ${BIN_ENV} to the ${CLI} binary, or unset ${HOOKS_PATH_KEY} to opt out`,
+  })}`;
+}
+
+/**
+ * A line only a chained shim carries.
+ *
+ * The same reason `renderShim` bakes in its event rather than reading `$0`: a
+ * shim's name cannot identify it, because the whole point of a chained shim is that
+ * it is called `post-commit` because the repository called its hook that. Identity
+ * has to come from the bytes, so this marker is what `hooks status` and `compare`
+ * read to tell our shim from somebody else's.
+ */
+export const CHAIN_MARKER = '# simt-dev chain-shim: the repository hook below still runs';
+
+/**
+ * A shim for an event this tool does not gate, so the repository's own hook keeps
+ * running after routing.
+ *
+ * `core.hooksPath` does not select a directory for the events this tool cares about
+ * and leave the rest alone: git reads EVERY hook from the named directory and from
+ * nowhere else. So the moment routing lands, a repository whose `post-commit` does
+ * real work loses it - not loudly, because nothing failed, only silently, because
+ * there is now no `post-commit` where git looks for one.
+ *
+ * There is nothing to enforce on such an event, so this shim does not run the
+ * dispatcher at all. It runs the hook it found and forwards git's arguments, which
+ * the dispatcher shim deliberately does not do: the program on the other end here is
+ * the repository's own hook and expects them.
+ *
+ * `target` is relative to the repository's top level wherever it can be. A path
+ * baked in absolute would break the first time anyone moves or clones the
+ * repository somewhere else, which for a hook is the difference between a gate that
+ * runs and one that stops existing.
+ *
+ * @param {string} event the hook event, e.g. `post-commit`. Not required to be in
+ *   {@link EVENTS}: that list is what this tool gates, and chaining exists precisely
+ *   for the events it does not.
+ * @param {string} target the repository's hook, relative to its top level or absolute
+ * @returns {string} POSIX sh source, LF-terminated, executable
+ */
+export function renderChainedShim(event, target) {
+  const D = '$';
+  return `#!/bin/sh
+# Generated by simt-dev. Do not edit.
+${CHAIN_MARKER}
+#
+# simt-dev does not gate ${event}, so nothing in this file enforces anything. It is
+# here because git reads every hook from ${HOOKS_DIR} once core.hooksPath points
+# there, and without this file the repository's own ${event} would stop running.
+#
+# It runs, in order:
+#   1. ${target}
+# forwarding git's arguments, which that hook expects. Reinstall with:
+# ${CLI} hooks install --yes
+
+set -eu
+
+ROOT="${D}(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+TARGET='${target}'
+case "${D}TARGET" in
+  /*) ;;
+  *) TARGET="${D}ROOT/${D}TARGET" ;;
+esac
+
+if [ ! -x "${D}TARGET" ]; then
+  echo "simt: ${event} is chained to a hook that is not there." >&2
+  echo "  expected: ${D}TARGET" >&2
+  echo "REMEDY restore that file, or delete ${fileFor(event)} to stop chaining it." >&2
+  exit 1
+fi
+
+exec "${D}TARGET" "${D}@"
+`;
+}

simt_dev/vendored/src/hooks/where.mjs

@@ -0,0 +1,118 @@
+// Work out which directory git will actually run hooks from.
+//
+// This exists because "core.hooksPath is unset" does NOT mean "git runs no
+// hooks". Unset means git falls back to the default location, which in a normal
+// repository is `.git/hooks` and in a linked worktree is the *main* repository's
+// `.git/hooks`. A tool that reads unset as "none" reports a live hand-written
+// hook as absent, and then installs over it without asking.
+//
+// `git rev-parse --git-path hooks` looks like the answer and is not one:
+//   normal repo, unset        -> ".git/hooks"   (relative, correct here)
+//   worktree, configured      -> "hooks"        (relative to the worktree top)
+//   worktree, unset           -> "./"           <- nonsense; the worktree's .git
+//                                                    is a FILE, so this names the
+//                                                    whole repository
+// An implementation that trusted it would enumerate a worktree's entire root as
+// its hooks directory and report every file in the repo as a hook. So the rule is
+// resolved here, from the two facts git does report reliably.
+//
+// ADR-012 dropped Windows, but nothing here is POSIX-specific; the worktree
+// handling is the only subtlety and it is the same on every platform.
+
+import { execFile } from 'node:child_process';
+import { readdir, stat } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+async function git(root, args) {
+  const { stdout } = await exec('git', args, { cwd: root });
+  return stdout.trim();
+}
+
+/**
+ * The directory git runs hooks from, and which of the two rules produced it.
+ *
+ * @param {string} root
+ * @returns {Promise<{dir:string, how:'configured'|'default'|'not-a-repo', top:string|null,
+ *                    commonDir:string|null, reason?:string}>}
+ */
+export async function resolveHooksDir(root) {
+  let top;
+  try {
+    top = await git(root, ['rev-parse', '--show-toplevel']);
+  } catch {
+    return { dir: join(root, '.git', 'hooks'), how: 'not-a-repo', top: null, commonDir: null, reason: 'not a git repository' };
+  }
+
+  let configured = null;
+  try {
+    const value = await git(root, ['config', '--get', 'core.hooksPath']);
+    configured = value === '' ? null : value;
+  } catch {
+    configured = null;
+  }
+
+  // Rule 1: core.hooksPath wins. A relative value resolves against the top level
+  // of the working tree, which is what makes a `hooks` directory work.
+  if (configured !== null) {
+    return {
+      dir: isAbsolute(configured) ? configured : resolve(top, configured),
+      how: 'configured',
+      top,
+      commonDir: null,
+    };
+  }
+
+  // Rule 2: the default, which is inside the COMMON git dir. A linked worktree
+  // has its own git dir but shares hooks with its parent, so this is the one
+  // step where `root/.git` is the wrong answer.
+  let common = '.git';
+  try {
+    common = await git(root, ['rev-parse', '--git-common-dir']);
+  } catch {
+    // A repository whose common dir cannot be read still has a working tree;
+    // the top-level .git guess is the only thing left and may be right.
+  }
+  return {
+    dir: isAbsolute(common) ? join(common, 'hooks') : resolve(top, common, 'hooks'),
+    how: 'default',
+    top,
+    commonDir: common,
+  };
+}
+
+/**
+ * Executable hooks git will actually run, excluding git's own `*.sample`
+ * templates and anything simt-dev generated.
+ *
+ * @param {string} root
+ * @returns {Promise<{event:string, path:string, bytes:number}[]>}
+ */
+export async function foreignHooks(root) {
+  const { dir, how } = await resolveHooksDir(root);
+  if (how === 'not-a-repo') return [];
+
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const found = [];
+  for (const name of entries.sort()) {
+    if (name.endsWith('.sample')) continue;
+    const path = join(dir, name);
+    let info;
+    try {
+      info = await stat(path);
+    } catch {
+      continue;
+    }
+    if (!info.isFile() || (info.mode & 0o111) === 0) continue;
+    found.push({ event: name, path, bytes: info.size });
+  }
+  return found;
+}

simt_dev/vendored/src/identity.mjs

@@ -0,0 +1,218 @@
+// The per-developer git identity, as a file the repository does not track.
+//
+// A repository has more than one person in it, and each of them may already have an
+// identity this tool has no business choosing. So the rules here are conservative in
+// that order:
+//
+//   1. If `git.config` already exists, it is left exactly as it is. Not updated, not
+//      merged, not reformatted. It may have been written by a person, by an older
+//      version of this tool, or by hand years ago, and none of those are this tool's
+//      to second-guess.
+//   2. Otherwise the identity comes from the repository's own last commit author.
+//      That is the person who has been working here, which is the best available
+//      answer to "who commits here" and requires no guessing: it is a fact, not a
+//      default.
+//   3. Otherwise from the git identity configured for this machine or this user,
+//      which is what would have been used anyway had this file never existed.
+//   4. Otherwise nothing is written. An identity nobody configured is not one to
+//      invent, and a file with a placeholder in it is worse than no file: git would
+//      use the placeholder.
+//
+// The file is deliberately NOT written into the repository's tracked files. It holds
+// whoever is committing, and committing it publishes one developer's name and email
+// to everybody else in the repository. `init` adds it to .gitignore when it creates
+// one; a repository that already tracks it is left that way, because removing a
+// tracked file is not something an adopting command should do silently.
+
+import { execFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+/** The file, at the repository root. Named for what it is: a git config fragment. */
+export const IDENTITY_FILE = 'git.config';
+
+/** The git config key that pulls the file in. */
+export const INCLUDE_KEY = 'include.path';
+
+/**
+ * Run a git command and return trimmed stdout, or null if it fails.
+ *
+ * Null rather than an exception for every case: a repository that is not a git
+ * repository, a version of git that does not know a flag, a machine with no
+ * configured identity. None of those is an error worth refusing an adoption over.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {Promise<string|null>}
+ */
+async function git(cwd, args) {
+  try {
+    const { stdout } = await exec('git', args, { cwd });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Who last committed here.
+ *
+ * `%an` and `%ae` rather than the configured identity on purpose: this is what
+ * actually happened, which is the answer to the question being asked. Reading
+ * `git config user.email` here would return the value this file is about to be
+ * derived from, and the step would be circular.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string|null, email: string|null}>}
+ */
+export async function lastCommitAuthor(root) {
+  const line = await git(root, ['log', '-1', '--format=%an <%ae>']);
+  if (!line) return { name: null, email: null };
+  // The name may itself contain angle brackets, so the address is split off the
+  // LAST one rather than the first.
+  const at = line.lastIndexOf('<');
+  const close = line.lastIndexOf('>');
+  if (at === -1 || close < at) return { name: line || null, email: null };
+  return {
+    name: line.slice(0, at).trim() || null,
+    email: line.slice(at + 1, close).trim() || null,
+  };
+}
+
+/**
+ * The identity this machine would use anyway.
+ *
+ * `--get` rather than `--global`: it resolves through system, global and local in
+ * git's own order, so what it returns is what a commit would have used had this file
+ * never been created. That is the fallback's whole point - it must not be a second
+ * opinion about what identity means.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string|null, email: string|null}>}
+ */
+export async function configuredIdentity(root) {
+  const read = async (key) => {
+    const value = await git(root, ['config', '--get', key]);
+    return value && value !== '' ? value : null;
+  };
+  return { name: await read('user.name'), email: await read('user.email') };
+}
+
+/**
+ * The identity to write, and where it came from.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string|null, email: string|null, from: 'last-commit'|'configured'|null,
+ *                    exists: boolean, bytes: number}>}
+ */
+export async function resolveIdentity(root) {
+  const path = join(root, IDENTITY_FILE);
+  try {
+    const info = await stat(path);
+    if (info.isFile()) {
+      return { name: null, email: null, from: null, exists: true, bytes: info.size };
+    }
+  } catch {
+    // Absent is the case this whole module exists for.
+  }
+
+  const committed = await lastCommitAuthor(root);
+  if (committed.name && committed.email) {
+    return { ...committed, from: 'last-commit', exists: false, bytes: 0 };
+  }
+  const configured = await configuredIdentity(root);
+  if (configured.name || configured.email) {
+    return { ...configured, from: 'configured', exists: false, bytes: 0 };
+  }
+  return { name: null, email: null, from: null, exists: false, bytes: 0 };
+}
+
+/**
+ * The file's bytes.
+ *
+ * Only the keys that were found are written. A partial identity is written as a
+ * partial identity rather than padded with a placeholder, because a placeholder is
+ * an identity git would use.
+ *
+ * @param {{name: string|null, email: string|null}} identity
+ * @returns {string} LF-terminated
+ */
+export function renderIdentityFile({ name, email }) {
+  const lines = ['[user]'];
+  if (name) lines.push(`\tname = ${name}`);
+  if (email) lines.push(`\temail = ${email}`);
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Whether `include.path` already names this repository's own file.
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>}
+ */
+export async function includesOwnIdentity(root) {
+  const values = (await git(root, ['config', '--local', '--get-all', INCLUDE_KEY])) ?? '';
+  return values.split('\n').map((v) => v.trim()).filter(Boolean).includes(`../${IDENTITY_FILE}`);
+}
+
+/**
+ * Point `core.hooksPath`-style local config at this repository's own identity file.
+ *
+ * `--replace-all` rather than `--add`, and that is the whole point: a value naming
+ * ANOTHER repository's identity file is not an addition to keep, it is a link to
+ * break. Two of the repositories here had exactly that, and both worked only because
+ * the sibling checkout happened to exist at the expected relative path.
+ *
+ * @param {string} root
+ * @returns {Promise<void>}
+ */
+export async function includeOwnIdentity(root) {
+  await git(root, ['config', '--local', '--replace-all', INCLUDE_KEY, `../${IDENTITY_FILE}`]);
+}
+
+/**
+ * Whether the repository tracks the identity file, which it should not.
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>}
+ */
+export async function tracksIdentity(root) {
+  const listed = await git(root, ['ls-files', '--error-unmatch', IDENTITY_FILE]);
+  return listed === IDENTITY_FILE;
+}
+
+/**
+ * Add the identity file to .gitignore, if it is not already there.
+ *
+ * Matching on the exact line rather than a substring, because a `.gitignore`
+ * entry of `/git.config` or `git.config` both mean it while a comment mentioning
+ * it means nothing, and appending a duplicate of an entry that is already present
+ * is how a file ends up listed twice.
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>} whether the file was changed
+ */
+export async function ignoreIdentity(root) {
+  const path = join(root, '.gitignore');
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    text = '';
+  }
+  const already = text.split('\n').map((l) => l.trim()).includes(IDENTITY_FILE);
+  if (already) return false;
+  const prefix = text === '' || text.endsWith('\n') ? '' : '\n';
+  const block =
+    `${prefix}\n` +
+    '# Per-developer git identity, written by `simt init`. Not a file to share:\n' +
+    '# it carries whoever is committing into the tree, and a repository has more than\n' +
+    '# one of those.\n' +
+    `${IDENTITY_FILE}\n`;
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(path, text + block);
+  return true;
+}

simt_dev/vendored/src/locate.mjs

@@ -0,0 +1,75 @@
+// Find the simt-dev binary, in POSIX sh, as one block of text.
+//
+// Two generated files run simt-dev on someone else's machine and must agree about
+// how it is found: the hook shim (src/hooks/shim.mjs) and the CI workflow
+// (src/ci/workflow.mjs). They were written separately and the second copy would
+// have been a real divergence risk - a change to the resolution order that reaches
+// the hook but not the workflow means the gate passes locally and is unfindable in
+// CI, which is the failure this whole tool is about.
+//
+// The caller's shell is expected to have `set -eu` and a `ROOT` already defined:
+// the shim derives ROOT from git, the workflow takes it from the runner. That is why
+// this is a block and not a script.
+
+import { BIN_ENV, BIN_REL, CLI, PACKAGE_NAME } from './name.mjs';
+
+/**
+ * @param {string} command arguments to hand the tool, with `$ROOT` spelled as a shell
+ *   expansion - `hooks run pre-commit --root "$ROOT"`, `check --root "$ROOT"`
+ * @param {object} [opts]
+ * @param {string} [opts.subject] what it could not find, as the caller names it:
+ *   the shim says "the dispatcher", the workflow says the command
+ * @param {string} [opts.remedy] the last line, which is the only part that differs
+ *   between a hook (which can be opted out of) and a CI job (which cannot)
+ * @returns {string} POSIX sh source
+ */
+export function renderLocator(command, { subject = CLI, remedy = `REMEDY run: npm i -D ${PACKAGE_NAME}` } = {}) {
+  const D = '$';
+  return `# ${D}${BIN_ENV} must name ONE program: an executable on PATH, or a .mjs entry
+# point to hand to node. It cannot be a command line, because there is no safe way
+# to split one in sh without eval, and a value with a space is refused rather than
+# half-executed - running from a source checkout is normal for anyone working on
+# this project itself, so this path has to work with no install step.
+run_simt_dev() {
+  case "${D}1" in
+    *' '*)
+      echo "${CLI}: ${D}${BIN_ENV} names a command line, not a program." >&2
+      echo "  set it to a single executable or a .mjs path, e.g." >&2
+      echo "    ${BIN_ENV}=/path/to/checkout/${BIN_REL}" >&2
+      exit 1
+      ;;
+    *.mjs)
+      # shift first: "${D}@" still holds ${D}1, which would pass the program path to
+      # itself as the first argument.
+      program="${D}1"
+      shift
+      exec node "${D}program" "${D}@"
+      ;;
+    *)
+      exec "${D}1" "${D}@"
+      ;;
+  esac
+}
+
+if [ -n "${D}{${BIN_ENV}:-}" ]; then
+  run_simt_dev "${D}${BIN_ENV}" ${command}
+fi
+
+if [ -f "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ]; then
+  exec node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
+fi
+
+if command -v ${CLI} >/dev/null 2>&1; then
+  exec ${CLI} ${command}
+fi
+
+echo "${CLI}: cannot locate ${subject}." >&2
+# Every expansion in these diagnostics must carry a default. Under \`set -eu\` an
+# unbound variable aborts the shell, so an unguarded ${D}${BIN_ENV} here would
+# kill the message that exists to explain the failure - and this block only runs
+# when nothing resolved, which is the one moment the reader needs it.
+echo "  looked for: ${D}{${BIN_ENV}:-<unset>}, ${D}ROOT/node_modules/${PACKAGE_NAME}, ${CLI} on PATH" >&2
+echo "${remedy}" >&2
+exit 1
+`;
+}