codetrellis 0.0.0-stage → 0.3.0

package/src/backend/services/criterion-checks.js

@@ -0,0 +1,387 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var criterion_checks_exports = {};
+__export(criterion_checks_exports, {
+  MAX_CHECK_READ_BYTES: () => MAX_CHECK_READ_BYTES,
+  MTIME_SLACK_MS: () => MTIME_SLACK_MS,
+  checkLocator: () => checkLocator,
+  junitCounts: () => junitCounts,
+  mp4DurationSeconds: () => mp4DurationSeconds,
+  pdfPageCount: () => pdfPageCount,
+  runChecks: () => runChecks,
+  workbookSheets: () => workbookSheets
+});
+module.exports = __toCommonJS(criterion_checks_exports);
+var import_junit = require("./tests/junit");
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_confined_fs = require("./confined-fs");
+var import_zip_entries = require("../lib/zip-entries");
+var import_xlsx_xml = require("../../shared/lib/xlsx-xml");
+var import_locator = require("../../shared/lib/locator");
+var import_csv = require("../../shared/lib/csv");
+var import_material_place = require("./material-place");
+var import_cloud_files = require("./cloud-files");
+const MAX_CHECK_READ_BYTES = 50 * 1024 * 1024;
+const MTIME_SLACK_MS = 2e3;
+const pass = (message, attachmentUid = null) => ({ status: "pass", message, attachmentUid });
+const fail = (message, attachmentUid = null) => ({ status: "fail", message, attachmentUid });
+const unverified = (message, attachmentUid = null) => ({ status: "unverified", message, attachmentUid });
+function readForCheck(projectRoot, a) {
+  const at = (0, import_material_place.locateStored)(a.path, projectRoot);
+  if (!at) return { ok: false, finding: unverified(`${a.path} is in a plans folder not linked on this device, so it was not checked`, a.uid) };
+  const { root, rel } = at;
+  try {
+    const abs = (0, import_confined_fs.resolveWithin)(root, rel, "artefact");
+    const st = import_node_fs.default.lstatSync(abs);
+    if (!st.isFile()) return { ok: false, finding: fail(`${a.path} is no longer a regular file in the project`, a.uid) };
+    if ((0, import_cloud_files.isPlaceholder)(abs)) return { ok: false, finding: unverified(`${a.path} is not on this device yet, so its contents were not checked`, a.uid) };
+    if (st.size > MAX_CHECK_READ_BYTES) {
+      return { ok: false, finding: unverified(`${a.path} is larger than ${MAX_CHECK_READ_BYTES / 1024 / 1024} MB, so its contents were not checked`, a.uid) };
+    }
+    return { ok: true, buf: (0, import_confined_fs.readFileWithin)(root, rel, "artefact") };
+  } catch {
+    return { ok: false, finding: fail(`${a.path} is not in the project any more, or is now a link`, a.uid) };
+  }
+}
+const extOf = (p) => import_node_path.default.extname(p).slice(1).toLowerCase();
+function zipText(buf, name, entries) {
+  const b = (0, import_zip_entries.readZipEntry)(buf, name, { entries });
+  return b ? b.toString("utf8") : null;
+}
+function workbookSheets(buf) {
+  const entries = (0, import_zip_entries.listZipEntries)(buf);
+  const workbook = zipText(buf, "xl/workbook.xml", entries);
+  if (!workbook) throw new Error("no xl/workbook.xml");
+  const rels = zipText(buf, "xl/_rels/workbook.xml.rels", entries) ?? "";
+  return (0, import_xlsx_xml.parseWorkbookSheets)(workbook, rels).map((s) => {
+    const xml = s.part ? zipText(buf, s.part, entries) : null;
+    return { name: s.name, dimension: xml ? (0, import_xlsx_xml.sheetDimension)(xml) : null };
+  });
+}
+function officeText(buf, ext) {
+  const entries = (0, import_zip_entries.listZipEntries)(buf);
+  const parts = ext === "docx" ? ["word/document.xml"] : ext === "pptx" ? entries.map((e) => e.name).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n)) : ["xl/sharedStrings.xml"];
+  return parts.map((p) => zipText(buf, p, entries) ?? "").map((xml) => (0, import_xlsx_xml.decodeXml)(xml.replace(/<\/(w:p|a:p|si)>/g, "\n").replace(/<[^>]+>/g, ""))).join("\n");
+}
+function slideCount(buf) {
+  return (0, import_zip_entries.listZipEntries)(buf).filter((e) => /^ppt\/slides\/slide\d+\.xml$/.test(e.name)).length;
+}
+function pdfPageCount(buf) {
+  const s = buf.toString("latin1");
+  let best = 0;
+  for (const m of s.matchAll(/<<(?:(?!<<|>>)[\s\S])*?\/Type\s*\/Pages\b(?:(?!<<|>>)[\s\S])*?>>/g)) {
+    const count = m[0].match(/\/Count\s+(\d+)/);
+    if (count) best = Math.max(best, Number(count[1]));
+  }
+  if (best > 0) return best;
+  const pages = s.match(/\/Type\s*\/Page(?![a-zA-Z])/g)?.length ?? 0;
+  return pages > 0 ? pages : null;
+}
+function mp4DurationSeconds(buf) {
+  const i = buf.indexOf("mvhd", 0, "latin1");
+  if (i < 0 || i + 32 > buf.length) return null;
+  const version = buf[i + 4];
+  const timescale = version === 1 ? buf.readUInt32BE(i + 24) : buf.readUInt32BE(i + 16);
+  const duration = version === 1 ? Number(buf.readBigUInt64BE(i + 28)) : buf.readUInt32BE(i + 20);
+  return timescale > 0 ? duration / timescale : null;
+}
+function rangeInside(range, dimension) {
+  const r = (0, import_locator.parseRange)(range);
+  const d = (0, import_locator.parseRange)(dimension);
+  if (!r || !d) return true;
+  return r.from.col >= d.from.col && r.from.row >= d.from.row && r.to.col <= d.to.col && r.to.row <= d.to.row;
+}
+function toSeconds(t) {
+  if (typeof t === "number" && Number.isFinite(t)) return t;
+  if (typeof t !== "string") return null;
+  const parts = t.trim().split(":").map(Number);
+  if (parts.some((n) => !Number.isFinite(n))) return null;
+  return parts.reduce((acc, n) => acc * 60 + n, 0);
+}
+const squash = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+function checkLocator(root, a, locator) {
+  if (!locator || typeof locator !== "object" || Array.isArray(locator)) {
+    return [fail(`The locator for ${a.path} must be an object such as {"sheet": "Regional", "range": "C14"}`, a.uid)];
+  }
+  const loc = locator;
+  const ext = extOf(a.path);
+  const read = readForCheck(root, a);
+  if (!read.ok) return [read.finding];
+  const buf = read.buf;
+  const out = [];
+  const known = /* @__PURE__ */ new Set(["sheet", "range", "page", "t", "lines", "text"]);
+  try {
+    if ("sheet" in loc || "range" in loc) {
+      const sheet = typeof loc.sheet === "string" ? loc.sheet : null;
+      const range = typeof loc.range === "string" ? loc.range.trim() : null;
+      if (range !== null && !(0, import_locator.parseRange)(range)) {
+        out.push(fail(`"${range}" is not a cell or range \u2014 write it as C14 or A1:F20`, a.uid));
+      } else if (ext === "xlsx" || ext === "xlsm") {
+        const sheets = workbookSheets(buf);
+        const target = sheet === null ? sheets[0] : sheets.find((s) => s.name === sheet);
+        if (!target) {
+          out.push(fail(`${a.path} has no sheet "${sheet}" \u2014 it has ${sheets.map((s) => `"${s.name}"`).join(", ") || "none"}`, a.uid));
+        } else if (range && target.dimension && !rangeInside(range, target.dimension)) {
+          out.push(fail(`${target.name}!${range} is outside what ${a.path} has in that sheet (${target.dimension})`, a.uid));
+        } else {
+          out.push(pass(`${a.path} has ${range ? `${target.name}!${range}` : `a sheet "${target.name}"`}`, a.uid));
+        }
+      } else if (ext === "csv") {
+        const { rows, cols } = (0, import_csv.csvShape)((0, import_csv.parseCsv)(buf.toString("utf8")));
+        const r = range ? (0, import_locator.parseRange)(range) : null;
+        if (r && (r.to.row > rows || r.to.col > cols)) {
+          out.push(fail(`${range} is outside ${a.path}, which has ${rows} rows and ${cols} columns`, a.uid));
+        } else {
+          out.push(pass(`${a.path} has ${range ?? "that sheet"}`, a.uid));
+        }
+      } else if (ext === "xls") {
+        out.push(unverified(`${a.path} is an old-format workbook; its sheets are not read yet`, a.uid));
+      } else {
+        out.push(fail(`A {sheet, range} locator points into a workbook; ${a.path} is a .${ext} file`, a.uid));
+      }
+    }
+    if ("page" in loc) {
+      const page = loc.page;
+      if (typeof page !== "number" || !Number.isInteger(page) || page < 1) {
+        out.push(fail(`page must be a whole number from 1 \u2014 got ${JSON.stringify(page)}`, a.uid));
+      } else {
+        const count = ext === "pdf" ? pdfPageCount(buf) : ext === "pptx" ? slideCount(buf) : void 0;
+        if (count === void 0) {
+          out.push(ext === "docx" ? unverified(`${a.path} is a Word document; its pages depend on layout and are not checked`, a.uid) : fail(`A {page} locator points into a PDF or a deck; ${a.path} is a .${ext} file`, a.uid));
+        } else if (count === null) {
+          out.push(unverified(`The page count of ${a.path} could not be read`, a.uid));
+        } else if (page > count) {
+          out.push(fail(`${a.path} has ${count} ${ext === "pptx" ? "slides" : "pages"}; ${page} is not one of them`, a.uid));
+        } else {
+          out.push(pass(`${a.path} has ${ext === "pptx" ? "slide" : "page"} ${page}`, a.uid));
+        }
+      }
+    }
+    if ("t" in loc) {
+      const t = toSeconds(loc.t);
+      if (t === null || t < 0) {
+        out.push(fail(`t must be seconds or mm:ss \u2014 got ${JSON.stringify(loc.t)}`, a.uid));
+      } else if (ext === "mp4" || ext === "mov") {
+        const d = mp4DurationSeconds(buf);
+        if (d === null) out.push(unverified(`The length of ${a.path} could not be read`, a.uid));
+        else if (t > d) out.push(fail(`${a.path} is ${Math.round(d)}s long; ${loc.t} is past the end`, a.uid));
+        else out.push(pass(`${a.path} reaches ${loc.t}`, a.uid));
+      } else if (ext === "webm") {
+        out.push(unverified(`The length of a .webm file is not read yet`, a.uid));
+      } else {
+        out.push(fail(`A {t} locator points into a video; ${a.path} is a .${ext} file`, a.uid));
+      }
+    }
+    if ("lines" in loc) {
+      const span = (0, import_locator.toSpan)(loc.lines);
+      if (!span || span.start < 1 || span.end < span.start) {
+        out.push(fail(`lines must be a line number or a span such as "10-20" \u2014 got ${JSON.stringify(loc.lines)}`, a.uid));
+      } else if (!import_locator.TEXT_EXTS.has(ext)) {
+        out.push(fail(`A {lines} locator points into a text file; ${a.path} is a .${ext} file`, a.uid));
+      } else {
+        const count = buf.toString("utf8").split(/\r?\n/).length;
+        if (span.end > count) out.push(fail(`${a.path} has ${count} lines; ${span.end} is past the end`, a.uid));
+        else out.push(pass(`${a.path} has lines ${span.start}${span.end !== span.start ? `\u2013${span.end}` : ""}`, a.uid));
+      }
+    }
+    if ("text" in loc) {
+      const quote = typeof loc.text === "string" ? squash(loc.text) : "";
+      if (!quote) {
+        out.push(fail(`text must be the words being cited`, a.uid));
+      } else {
+        const body = import_locator.TEXT_EXTS.has(ext) ? buf.toString("utf8") : ext === "docx" || ext === "pptx" || ext === "xlsx" || ext === "xlsm" ? officeText(buf, ext) : null;
+        if (body === null) out.push(unverified(`Text is not read from .${ext} files yet, so the quote was not checked`, a.uid));
+        else if (!squash(body).includes(quote)) out.push(fail(`${a.path} does not contain "${String(loc.text).slice(0, 80)}"`, a.uid));
+        else out.push(pass(`${a.path} contains the quoted words`, a.uid));
+      }
+    }
+  } catch (err) {
+    out.push(unverified(`${a.path} could not be read as a .${ext} file (${err.message})`, a.uid));
+  }
+  const unknown = Object.keys(loc).filter((k) => !known.has(k));
+  if (unknown.length) {
+    out.push(unverified(`Locator keys ${unknown.join(", ")} are not ones CodeTrellis checks`, a.uid));
+  }
+  if (out.length === 0) out.push(fail(`The locator for ${a.path} names no place \u2014 use sheet/range, page, t, lines or text`, a.uid));
+  return out;
+}
+function junitCounts(xml) {
+  const attr = (tag, name) => Number(tag.match(new RegExp(`\\b${name}="(\\d+)"`))?.[1] ?? 0);
+  const top = xml.match(/<testsuites\b[^>]*>/);
+  if (top && /\btests="\d+"/.test(top[0])) {
+    return { tests: attr(top[0], "tests"), failures: attr(top[0], "failures"), errors: attr(top[0], "errors") };
+  }
+  const suites = [...xml.matchAll(/<testsuite\b[^>]*>/g)].map((m) => m[0]);
+  if (suites.length === 0) return null;
+  return suites.reduce(
+    (acc, s) => ({ tests: acc.tests + attr(s, "tests"), failures: acc.failures + attr(s, "failures"), errors: acc.errors + attr(s, "errors") }),
+    { tests: 0, failures: 0, errors: 0 }
+  );
+}
+const when = (ms) => new Date(ms).toISOString().slice(0, 16).replace("T", " ");
+function runChecks(ctx) {
+  const findings = [];
+  const { root } = ctx;
+  const kind = ctx.criterion.kind;
+  const offered = ctx.evidence.filter((e) => e.attachmentUid);
+  if (kind !== "manual") {
+    for (const e of offered) {
+      if (!e.artefact) {
+        findings.push(fail(
+          `Attachment ${e.attachmentUid} is not a file recorded on this item \u2014 record it with record_artefact first`,
+          e.attachmentUid
+        ));
+      } else if (!e.artefact.sha256) {
+        findings.push(fail(`${e.artefact.path} is no longer in the project`, e.artefact.uid));
+      }
+    }
+  }
+  if (!root && kind !== "manual") {
+    findings.push(unverified("This item's project is not open in CodeTrellis, so its files could not be checked"));
+    return finish(ctx, findings);
+  }
+  const files = (roles) => {
+    const fromEvidence = offered.map((e) => e.artefact).filter((a) => !!a && !!a.sha256 && roles.includes(a.role));
+    return fromEvidence.length || offered.length ? fromEvidence : ctx.itemArtefacts.filter((a) => a.sha256 && roles.includes(a.role));
+  };
+  switch (kind) {
+    case "manual":
+      findings.push(pass("Nothing mechanical to check \u2014 this is a person's judgement"));
+      break;
+    case "artefact": {
+      const outputs = files(["output", "evidence"]);
+      if (outputs.length === 0) {
+        findings.push(fail('No output file is recorded for this item \u2014 record_artefact(path, role: "output") the file the work produced'));
+      }
+      for (const a of outputs) {
+        if (a.mtime !== null && a.mtime < ctx.itemStartedAt - MTIME_SLACK_MS) {
+          findings.push(fail(`${a.path} was last changed ${when(a.mtime)}, before this item started (${when(ctx.itemStartedAt)}) \u2014 it is not this work's output`, a.uid));
+        } else {
+          findings.push(pass(`${a.path} is in the project and changed since the item started`, a.uid));
+        }
+      }
+      break;
+    }
+    case "citation": {
+      const cited = ctx.evidence.filter((e) => e.artefact?.role === "material");
+      if (cited.length === 0) {
+        findings.push(fail('Cite the material this rests on: attach it as role "material" and give a locator \u2014 {sheet, range}, {page}, {lines}, {text} or {t}'));
+      }
+      for (const e of cited) {
+        if (e.locator === null || e.locator === void 0) {
+          findings.push(fail(`Citing ${e.artefact.path} needs a locator saying where in it`, e.artefact.uid));
+        }
+        if (ctx.materialsRead) {
+          findings.push(ctx.materialsRead.has(e.artefact.uid) ? pass(`${e.artefact.path} was read through read_material while this item was under way`, e.artefact.uid) : unverified(`${e.artefact.path} was not read through read_material while this item was under way, so nothing shows it was opened`, e.artefact.uid));
+        }
+      }
+      break;
+    }
+    case "test": {
+      const reports = files(["evidence", "output"]);
+      if (reports.length === 0) {
+        findings.push(fail("Attach the test report as evidence (a JUnit .xml, or the run's log)"));
+      }
+      for (const a of reports) {
+        if (ctx.lastTargetChangeAt !== null && a.mtime !== null && a.mtime < ctx.lastTargetChangeAt - MTIME_SLACK_MS) {
+          findings.push({
+            ...fail(`\u26A0 tests older than the code: ${a.path} ran ${when(a.mtime)}, before the last change to this item's files (${when(ctx.lastTargetChangeAt)}) \u2014 run the tests again`, a.uid),
+            reason: "tests_older"
+          });
+          continue;
+        }
+        const read = readForCheck(root, a);
+        if (!read.ok) {
+          findings.push(read.finding);
+          continue;
+        }
+        const xml = /\.xml$/i.test(a.path) ? read.buf.toString("utf8") : null;
+        const parsed = xml !== null ? (0, import_junit.parseJUnit)(xml) : null;
+        const counts = parsed && parsed.cases.length ? { tests: parsed.totals.tests, failures: parsed.totals.failed, errors: parsed.totals.errors } : xml !== null ? junitCounts(xml) : null;
+        if (counts && ctx.onTestReport) {
+          try {
+            ctx.onTestReport(a);
+          } catch {
+          }
+        }
+        if (!counts) {
+          findings.push(unverified(`${a.path} is not a JUnit report, so its pass and fail counts were not read`, a.uid));
+        } else if (counts.failures + counts.errors > 0) {
+          const cases = (parsed?.cases ?? []).filter((c) => c.result === "failed" || c.result === "error");
+          const named = cases.slice(0, 3).map((c) => `${(0, import_junit.testLabel)(c)}${c.message ? ` (${c.message})` : ""}`);
+          const more = cases.length > 3 ? `; and ${cases.length - 3} more` : "";
+          findings.push(fail(`${a.path} reports ${counts.failures + counts.errors} of ${counts.tests} tests failing${named.length ? `: ${named.join("; ")}${more}` : ""}`, a.uid));
+        } else if (counts.tests === 0) {
+          findings.push(fail(`${a.path} reports no tests run`, a.uid));
+        } else {
+          findings.push(pass(`${a.path}: ${counts.tests} tests, none failing`, a.uid));
+        }
+      }
+      break;
+    }
+    case "code": {
+      const code = ctx.code;
+      if (!code) break;
+      if ("unavailable" in code) findings.push(unverified(`The item's changes could not be reviewed: ${code.unavailable}`));
+      else if (code.verdict === "landed") findings.push(pass("Every file this item names has changed"));
+      else if (code.verdict === "no-targets") findings.push(unverified("This item names no files, so its changes cannot be checked"));
+      else if (code.verdict === "untouched") findings.push(fail(`None of this item's files have changed yet: ${code.missing.join(", ")}`));
+      else findings.push(fail(`Not changed yet: ${code.missing.join(", ")}`));
+      for (const s of ctx.openHighSignals ?? []) {
+        findings.push(fail(`A high overlap with other work is still open (${s.heading}): ${s.words} Answer it on the Awareness tab, or fix it, and check again.`));
+      }
+      break;
+    }
+  }
+  for (const e of ctx.evidence) {
+    if (e.artefact && e.artefact.sha256 && e.locator !== null && e.locator !== void 0) {
+      findings.push(...checkLocator(root, e.artefact, e.locator));
+    }
+  }
+  return finish(ctx, findings);
+}
+function finish(ctx, findings) {
+  return {
+    criterionUid: ctx.criterion.uid,
+    itemUid: ctx.criterion.itemUid,
+    ok: !findings.some((f) => f.status === "fail"),
+    findings
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAX_CHECK_READ_BYTES,
+  MTIME_SLACK_MS,
+  checkLocator,
+  junitCounts,
+  mp4DurationSeconds,
+  pdfPageCount,
+  runChecks,
+  workbookSheets
+});