simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/toolchain.mjs

@@ -0,0 +1,202 @@
+// What the repository pins, and whether those pins agree with each other.
+//
+// rules/stacks/node.md already makes four claims about this and enforces none of them:
+// one `packageManager` field matching the committed lockfile, a floor in `engines.node`,
+// a `.nvmrc` that agrees with both, and `engines` stated at all. This module is the
+// gate for those claims, so the file is read but never written: the values are the
+// repository's decisions and a version is not this tool's to pick.
+//
+// The one thing deliberately not checked is whether one repository's node major matches
+// another's. The plan called three `.nvmrc` files "disagreeing", and reading them showed
+// they agree with their own `engines` perfectly; what differs is a per-repository choice
+// that each one has a reason for. A check that reported that would be a check with no
+// remedy, and a gate whose finding cannot be acted on is the failure AGENTS.md exists to
+// prevent.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { fingerprint } from './resolve/fingerprint.mjs';
+import { readJsonc } from './tsconfig.mjs';
+
+export const LOCKFILES = [
+  { file: 'package-lock.json', manager: 'npm' },
+  { file: 'pnpm-lock.yaml', manager: 'pnpm' },
+  { file: 'yarn.lock', manager: 'yarn' },
+  { file: 'bun.lock', manager: 'bun' },
+  { file: 'bun.lockb', manager: 'bun' },
+];
+
+const PKG_FILE = 'package.json';
+const NVMRC_FILE = '.nvmrc';
+
+/**
+ * The comparators this tool will evaluate, and nothing else.
+ *
+ * A range it does not understand produces no finding rather than an approximate one: a
+ * wrong contradiction names two values that may well be fine, and a reader who cannot tell
+ * which of our readings was the guess stops trusting the ones we got right. Anything not
+ * listed here is deliberately silent.
+ *
+ * @returns {null | {min: number[], max: number[]|null, minExclusive: boolean}}
+ */
+function comparator(text) {
+  const operator = /^(>=|<=|>|<|\^|~|=)?\s*(\S+)$/.exec(text.trim());
+  const sign = operator[1] ?? '';
+  const version = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(operator[2].replace(/^[v=]+/, ''));
+  if (!version) return null;
+  const parts = [Number(version[1]), Number(version[2] ?? 0), Number(version[3] ?? 0)];
+  const major = parts[0];
+  const minor = parts[1];
+  const nextMinor = { min: parts, minExclusive: false, max: [major, minor + 1, 0], maxExclusive: true };
+  const unbounded = { max: null, maxExclusive: false };
+
+  if (sign === '>=') return { min: parts, minExclusive: false, ...unbounded };
+  if (sign === '>') return { min: parts, minExclusive: true, ...unbounded };
+  if (sign === '<=') return { min: null, minExclusive: false, max: parts, maxExclusive: false };
+  if (sign === '<') return { min: null, minExclusive: false, max: parts, maxExclusive: true };
+  if (sign === '^') {
+    const ceiling = major === 0 ? (minor === 0 ? [0, 0, parts[2] + 1] : [0, minor + 1, 0]) : [major + 1, 0, 0];
+    return { min: parts, minExclusive: false, max: ceiling, maxExclusive: true };
+  }
+  if (sign === '~') return nextMinor;
+  // A bare `22` means every 22, as npm reads it, and `22.1` every 22.1. Reading either as
+  // one exact version would report a matching pin as a contradiction.
+  if (version[3] !== undefined) return { min: parts, minExclusive: false, max: parts, maxExclusive: false };
+  if (version[2] !== undefined) return nextMinor;
+  return { min: parts, minExclusive: false, max: [major + 1, 0, 0], maxExclusive: true };
+}
+
+/** @returns {null | number[]} `null` when the range uses something this tool does not evaluate. */
+export function allows(range, version) {
+  const target = typeof version === 'string' ? version.trim().replace(/^[v=]+/, '') : version;
+  if (!/^\d+(\.\d+)*$/.test(String(target))) return null;
+  const wanted = String(target).split('.').map(Number);
+  const padded = [wanted[0], wanted[1] ?? 0, wanted[2] ?? 0];
+  const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+
+  // An `||` satisfies if any branch does; every branch must be readable or the answer is
+  // unknown rather than "no".
+  const branches = String(range).split('||');
+  const read = branches.map((branch) => branch.trim().split(/\s+/).map(comparator));
+  if (read.some((terms) => terms.some((term) => term === null))) return null;
+
+  return read.some((terms) =>
+    terms.every((term) => {
+      if (term.min !== null) {
+        const cmp = compare(padded, term.min);
+        if (cmp < 0 || (cmp === 0 && term.minExclusive)) return false;
+      }
+      if (term.max === null) return true;
+      const cmp = compare(padded, term.max);
+      return cmp < 0 || (cmp === 0 && !term.maxExclusive);
+    })
+  );
+}
+
+/**
+ * @returns {Promise<{manager: string, lockfile: string, declared: string|null,
+ *   engines: string|null, nvmrc: string|null}[]>} one entry per lockfile found
+ */
+export async function readPins(root) {
+  // `fingerprint().manifest` is this tool's own manifest, not package.json, so the node
+  // stack tag decides whether there is a package.json to read and the file is read here.
+  const { stack } = await fingerprint(root);
+  if (!stack.includes('node')) return [];
+  const text = await readFile(join(root, PKG_FILE), 'utf8').catch(() => null);
+  if (text === null) return [];
+  const { value: pkg, error } = readJsonc(text);
+  if (error !== null) return [];
+
+  const found = [];
+  for (const entry of LOCKFILES) {
+    if (!(await readFile(join(root, entry.file), 'utf8').then(() => true).catch(() => false))) continue;
+    found.push({
+      manager: entry.manager,
+      lockfile: entry.file,
+      declared: typeof pkg.packageManager === 'string' ? pkg.packageManager : null,
+      engines: pkg.engines && typeof pkg.engines.node === 'string' ? pkg.engines.node : null,
+      nvmrc: await readFile(join(root, NVMRC_FILE), 'utf8').then((t) => t.trim()).catch(() => null),
+    });
+  }
+  return found;
+}
+
+/**
+ * @returns {Promise<{file: string, status: string, detail: string, remedy: string}[]>}
+ */
+export async function checkToolchain(root) {
+  const pins = await readPins(root);
+  const findings = [];
+  const report = (file, status, detail, remedy) => findings.push({ file, status, detail, remedy });
+
+  if (pins.length === 0) return findings;
+
+  // Two lockfiles is not a disagreement this tool can resolve by picking one, so it is
+  // reported as what it is: the repository does not have a single package manager.
+  if (pins.length > 1) {
+    report(
+      PKG_FILE,
+      'mismatched',
+      `this repo has ${pins.length} lockfiles (${pins.map((p) => p.lockfile).join(', ')}), so the ` +
+        'package manager is whichever one each contributor installed',
+      'delete the lockfile for the manager this repo does not use, and commit the other one',
+    );
+    return findings;
+  }
+
+  const [pin] = pins;
+
+  if (pin.declared === null) {
+    report(
+      PKG_FILE,
+      'undeclared',
+      `this repo commits ${pin.lockfile} and declares no "packageManager", so the manager is ` +
+        'whoever installed it last and corepack is free to pick the other one',
+      `npm pkg set packageManager=${pin.manager}@$(npm --version)   (run it here; it fills in the version this machine has)`,
+    );
+  } else if (pin.declared.split('@')[0] !== pin.manager) {
+    report(
+      PKG_FILE,
+      'mismatched',
+      `"packageManager" says ${pin.declared} and this repo commits ${pin.lockfile}, so the field ` +
+        'pins a manager whose lockfile is not the one being committed',
+      `npm pkg set packageManager=${pin.manager}@$(npm --version)`,
+    );
+  }
+
+  if (pin.engines === null) {
+    // The remedy prefers the version the repository already pins over the one this machine
+    // happens to run. Taking the local one is what turns a single missing floor into two
+    // findings: a developer on a newer node than the repo's `.nvmrc` would floor above their
+    // own pin and be handed a contradiction the moment they acted on it.
+    const floor = pin.nvmrc !== null
+      ? `   (${NVMRC_FILE} already pins ${pin.nvmrc}; floor to that version, not to this machine's)`
+      : '   (run it here; it fills in the version this machine has)';
+    report(
+      PKG_FILE,
+      'unfloored',
+      `this repo commits ${pin.lockfile} and declares no "engines": {"node": ...}, so the floor ` +
+        'is a comment and the version is whatever CI happens to be running',
+      `node --version   (then add "engines": {"node": ">=<that version>"} to package.json)${floor}`,
+    );
+  }
+
+  // A `.nvmrc` that the declared floor forbids is the one contradiction in this file that
+  // has a single obvious answer, because the floor is the promise and the pin is the
+  // instance: the pin is the thing that must move.
+  if (pin.nvmrc !== null && pin.engines !== null) {
+    const satisfies = allows(pin.engines, pin.nvmrc);
+    if (satisfies === false) {
+      report(
+        NVMRC_FILE,
+        'contradiction',
+        `${NVMRC_FILE} pins ${pin.nvmrc} and "engines": {"node": "${pin.engines}"} does not allow it, ` +
+          'so the version a developer gets locally is one the project says it does not support',
+        `change ${NVMRC_FILE} to a version that satisfies "${pin.engines}", or raise "engines": {"node": ...} to cover ${pin.nvmrc}`,
+      );
+    }
+  }
+
+  return findings;
+}

simt_dev/vendored/src/tsconfig.mjs

@@ -0,0 +1,314 @@
+// `tsconfig.base.json`: the strictness floor every TypeScript repo in the estate agrees on.
+//
+// This is ADR-026's mechanism — a config whose grammar has no comments is a whole file the
+// repo owns from the first commit — pointed at the file ADR-025 ruled out by name. Two
+// consequences shape everything here, and both are easy to get wrong:
+//
+//   1. A base file is a FLOOR, not a policy. `extends` lets a child override any key, so a
+//      base can only repair a repo that is *missing* a flag. It can never repair one that
+//      spells a flag differently — the child wins and the base is inert for that key. Every
+//      key below is therefore one the estate already agrees on, and the one place the estate
+//      disagrees is a check instead (see `checkTsconfig`).
+//   2. The bytes cannot explain themselves. JSON has no comments, so this file ships with no
+//      header saying who wrote it or what a reader must do next, which is normally the one
+//      thing a shipped file owes its reader. `init` prints the `extends` line it requires
+//      and `check` reports a repo that has not adopted it, so the obligation is met by the
+//      tool's output rather than the file's.
+//
+// The whole file is owned by `init` alone. It is not in `src/ci/` and not in
+// `src/projection/baselines.mjs` because it is neither a `.github` file that `simt-dev ci`
+// refreshes nor a marker region: `simt-dev check` reports its absence and never its contents.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { fingerprint } from './resolve/fingerprint.mjs';
+import { CLI } from './name.mjs';
+
+export const TSCONFIG_BASE_FILE = 'tsconfig.base.json';
+export const TSCONFIG_FILE = 'tsconfig.json';
+
+/**
+ * The strictness floor.
+ *
+ * Every key here is already set, and set the same way, by every `tsconfig.json` in the
+ * estate that could afford it. One repository is the outlier and it is not one on purpose: it
+ * is missing the seven flags below that the three social repos share, which is the gap
+ * plan section 3.1 row 5 named. Nothing in this object is a value anybody has argued about;
+ * it is the intersection of what four repositories independently wrote.
+ *
+ * Absent, and each for a reason that would be invisible to the next reader:
+ *
+ *   - `noEmit`. node.md:36 wants it for "any project that bundles elsewhere", and it would
+ *     be harmless to inherit here because a child can set `false`. It is left out because a
+ *     base that hands `noEmit` to a repo nobody looked at is a build that stops emitting,
+ *     and the two repositories that bundle elsewhere did not ask for it. A floor nobody
+ *     opted into is not a floor.
+ *   - `moduleResolution`. All four repositories set it; three write `Bundler` and one writes
+ *     `bundler`. Shipping either would change nothing, because the child overrides the base
+ *     and the disagreement is precisely that the child sets it. `check` reports the spelling
+ *     instead.
+ *   - `target`, `lib`, `module`. Genuinely per-repo: `lib` is DOM+DOM.Iterable in two
+ *     repositories and DOM+WebWorker in the other two, and a base that chose would silence
+ *     one of them. These describe the platform, not the estate.
+ *   - `include`, `exclude`, `paths`, `types`, `jsx`. What a project is made of.
+ */
+export const STRICTNESS_FLOOR = {
+  strict: true,
+  noUncheckedIndexedAccess: true,
+  exactOptionalPropertyTypes: true,
+  noImplicitOverride: true,
+  useUnknownInCatchVariables: true,
+  noFallthroughCasesInSwitch: true,
+  noImplicitReturns: true,
+  isolatedModules: true,
+  verbatimModuleSyntax: true,
+  allowJs: false,
+  resolveJsonModule: true,
+  skipLibCheck: true,
+};
+
+/**
+ * `moduleResolution` as TypeScript documents it.
+ *
+ * The parser is case-insensitive, which is the whole reason the estate has drifted: both
+ * `bundler` and `Bundler` work, so nothing ever told anybody the other one did not. node.md:38
+ * asks for it "spelled consistently across every repo in the workspace", and consistency
+ * with an external document is the only spelling that can be checked in one repo at a time
+ * — consistency with the other repositories would need a workspace, and `check` runs in a
+ * repo on its own.
+ */
+export const DOCUMENTED_RESOLUTIONS = new Set([
+  'classic',
+  'node',
+  'node10',
+  'node16',
+  'nodenext',
+  'bundler',
+]);
+
+/**
+ * The base file, as bytes.
+ *
+ * Key order is the order of `STRICTNESS_FLOOR` and not alphabetical, because the object
+ * literal is the readable form and reordering it here would mean the file and the reason
+ * disagree. `JSON.stringify` preserves insertion order, so the two cannot drift.
+ *
+ * @returns {string} JSON, LF-terminated
+ */
+export function renderTsconfigBase() {
+  return `${JSON.stringify({ compilerOptions: STRICTNESS_FLOOR }, null, 2)}\n`;
+}
+
+/**
+ * Parse a file that TypeScript allows to carry comments.
+ *
+ * `tsconfig.json` is JSONC: tsc strips comments before reading it, so a repo with a comment
+ * at the top of its tsconfig is normal and not a mistake. A plain `JSON.parse` would throw,
+ * and a gate that throws on a file it did not write is worse than a gate that says nothing
+ * — the reader would see a stack trace where the answer was one line. Every failure here
+ * returns a value rather than throwing, so a malformed tsconfig is reported as unreadable
+ * and nothing else claims to know what is in it.
+ *
+ * Written as a scanner rather than a regex for one reason: `//` and `/*` occur inside
+ * strings, and the commonest string in a tsconfig-adjacent file is a URL. A regex would
+ * delete `https://` and then report a parse error on a file that is perfectly valid.
+ *
+ * @param {string} text
+ * @returns {{value: object|null, error: string|null}}
+ */
+export function readJsonc(text) {
+  let out = '';
+  let inString = false;
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (inString) {
+      if (c === '\\') {
+        out += c + (text[i + 1] ?? '');
+        i += 2;
+        continue;
+      }
+      if (c === '"') inString = false;
+      out += c;
+      i += 1;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      out += c;
+      i += 1;
+      continue;
+    }
+    if (c === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i += 1;
+      continue;
+    }
+    if (c === '/' && text[i + 1] === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i += 2;
+      continue;
+    }
+    // A trailing comma is legal in JSONC and illegal in JSON. Dropping it on the way out
+    // rather than with a regex over the finished string, because `, }` is also what a
+    // string containing a closing brace looks like.
+    if (c === '}' || c === ']') {
+      let end = out.length - 1;
+      while (end >= 0 && /\s/.test(out[end])) end -= 1;
+      if (out[end] === ',') out = out.slice(0, end) + out.slice(end + 1);
+    }
+    out += c;
+    i += 1;
+  }
+  try {
+    const value = JSON.parse(out);
+    return { value: typeof value === 'object' && value !== null ? value : null, error: null };
+  } catch (e) {
+    return { value: null, error: e.message };
+  }
+}
+
+/**
+ * What this repo's base file should be, and what should happen to it.
+ *
+ * There is no `refresh`. ADR-026 gave simt-dev's own `.github` files a refresh path because
+ * this repository is the template's only author; a base file has the same argument, and it
+ * is deliberately not extended to it. `simt-dev check` in this repository reports the
+ * baseline files as unmanaged by design, so a refresh path here would be a way to make this
+ * repository's own gate green by rewriting the file it is judging — which is the same
+ * mistake as a gate that edits its own expectations.
+ *
+ * The skip case is detection, not politeness: a repository with no TypeScript has nothing to
+ * extend the base, and a `tsconfig.base.json` in a JavaScript repository is a file that
+ * claims to be an authority and is read by nothing.
+ *
+ * @param {string} root repo root
+ * @returns {Promise<{file:string, path:string, action:'create'|'unchanged'|'skip',
+ *                    exists:boolean, bytes:number, current:boolean, typescript:boolean,
+ *                    reason:string|null}>}
+ */
+export async function planTsconfigBase(root) {
+  const path = join(root, TSCONFIG_BASE_FILE);
+  let text = null;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    text = null;
+  }
+  const exists = text !== null;
+  const bytes = exists ? Buffer.byteLength(text) : 0;
+  const { stack } = await fingerprint(root);
+  const typescript = stack.includes('typescript');
+  if (exists) {
+    return {
+      file: TSCONFIG_BASE_FILE,
+      path,
+      action: 'unchanged',
+      exists,
+      bytes,
+      current: true,
+      typescript,
+      reason: null,
+    };
+  }
+  return {
+    file: TSCONFIG_BASE_FILE,
+    path,
+    action: typescript ? 'create' : 'skip',
+    exists,
+    bytes: 0,
+    current: false,
+    typescript,
+    reason: typescript
+      ? null
+      : 'no TypeScript in this repository, so nothing would extend the base',
+  };
+}
+
+/**
+ * What is wrong with a repository's TypeScript configuration.
+ *
+ * Two findings, and the split between them is the point of the whole module. A base file
+ * repairs a repository that is missing a flag and is structurally unable to repair one that
+ * spells a flag differently, so exactly one of these two problems can be handed to a file
+ * and the other has to be a check.
+ *
+ * Returns `[]` rather than throwing on unreadable input, for the reason in `readJsonc`.
+ *
+ * @param {string} root repo root
+ * @returns {Promise<{file:string, status:string, detail:string, remedy:string}[]>}
+ */
+export async function checkTsconfig(root) {
+  const findings = [];
+
+  let baseExists = true;
+  try {
+    await readFile(join(root, TSCONFIG_BASE_FILE), 'utf8');
+  } catch {
+    baseExists = false;
+  }
+
+  const { stack } = await fingerprint(root);
+  const typescript = stack.includes('typescript');
+  if (typescript && !baseExists) {
+    findings.push({
+      file: TSCONFIG_BASE_FILE,
+      status: 'absent',
+      detail:
+        'this repo is TypeScript and has no base file, so every strictness flag is whatever ' +
+        'one person happened to write',
+      remedy: `${CLI} init --yes`,
+    });
+  }
+
+  // Nothing below reads the base file's contents, and that is deliberate. This tool does not
+  // own those bytes (ADR-026), so a repo that edited them is not drift — and a finding that
+  // compared them would report somebody's work as an error. Only the question of whether
+  // `tsconfig.json` points at the base is this tool's to ask.
+  let own = null;
+  try {
+    own = readJsonc(await readFile(join(root, TSCONFIG_FILE), 'utf8'));
+  } catch {
+    own = null;
+  }
+  if (own === null) return findings;
+  if (own.error !== null) {
+    // A file that cannot be parsed is a finding about `tsc`, not about simt-dev, and tsc
+    // says it better. Staying quiet here is the difference between a gate with an opinion
+    // and a gate that guesses.
+    return findings;
+  }
+  const config = own.value;
+  if (!config) return findings;
+
+  if (baseExists && config.extends === undefined) {
+    findings.push({
+      file: TSCONFIG_FILE,
+      status: 'inert',
+      detail:
+        `this repo has a ${TSCONFIG_BASE_FILE} that ${TSCONFIG_FILE} does not extend, so the ` +
+        'strictness floor is in the repository and not in effect',
+      remedy: `add "extends": "./${TSCONFIG_BASE_FILE}" to ${TSCONFIG_FILE}`,
+    });
+  }
+
+  const resolution = config.compilerOptions?.moduleResolution;
+  if (typeof resolution === 'string' && !DOCUMENTED_RESOLUTIONS.has(resolution)) {
+    const canonical = [...DOCUMENTED_RESOLUTIONS].find(
+      (r) => r.toLowerCase() === resolution.toLowerCase(),
+    );
+    if (canonical) {
+      findings.push({
+        file: TSCONFIG_FILE,
+        status: 'inconsistent',
+        detail:
+          `"moduleResolution": "${resolution}" compiles, which is why it disagrees with the ` +
+          `repositories that write "${canonical}" and why nothing has ever said so`,
+        remedy: `change it to "${canonical}"`,
+      });
+    }
+  }
+
+  return findings;
+}