@codyswann/lisa 2.346.0 → 2.348.0

package/expo/copy-overwrite/scripts/bdd/parse.mjs

@@ -0,0 +1,220 @@
+/**
+ * Gherkin feature parsing and repo-safe file resolution for the BDD gate.
+ *
+ * The parser is deliberately hand-rolled and dependency-free: the gate must
+ * run in a bare `node scripts/check-bdd-coverage.mjs` with no install step, in
+ * every repo, at a pinned Lisa revision.
+ *
+ * @module scripts/bdd/parse
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+  ID_PATTERN,
+  LIFECYCLE_TAGS,
+  PROVENANCE_PATTERN,
+  parseTrackerTag,
+} from "./contract.mjs";
+
+const LIFECYCLE = new Set(LIFECYCLE_TAGS);
+
+/** Normalize a path to posix separators so reports are OS-independent. */
+export const posix = value => value.split(path.sep).join("/");
+
+/**
+ * Resolve a coverage-map path inside the repo, refusing every escape.
+ *
+ * A coverage map is repo data that an author edits, so it is treated as
+ * untrusted input: absolute paths, `..` traversal, and symlinks that resolve
+ * outside the repo are rejected rather than followed. Refusing beats
+ * following — a mapping that reads a file outside the repo could "prove"
+ * coverage from anything on the runner.
+ * @param {string} root - Repo root.
+ * @param {string} relative - Repo-relative path from the coverage map.
+ * @returns {{path: string|null, error: string|null}} Absolute path, or the reason it was refused.
+ */
+export function resolveInsideRepo(root, relative) {
+  if (typeof relative !== "string" || relative.length === 0) {
+    return { path: null, error: "path is missing" };
+  }
+  if (path.isAbsolute(relative) || /^[a-zA-Z]:/.test(relative)) {
+    return { path: null, error: "path must be repo-relative" };
+  }
+  const resolvedRoot = fs.realpathSync(root);
+  const candidate = path.resolve(resolvedRoot, relative);
+  if (!isInside(resolvedRoot, candidate)) {
+    return { path: null, error: "path escapes the repository" };
+  }
+  if (!fs.existsSync(candidate)) return { path: null, error: "file not found" };
+  const real = fs.realpathSync(candidate);
+  if (!isInside(resolvedRoot, real)) {
+    return { path: null, error: "symlink resolves outside the repository" };
+  }
+  return { path: real, error: null };
+}
+
+/**
+ * True when `child` is `parent` or lives under it.
+ * @param {string} parent - Containing directory.
+ * @param {string} child - Candidate path.
+ * @returns {boolean} Whether the candidate is contained.
+ */
+function isInside(parent, child) {
+  const relative = path.relative(parent, child);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+/**
+ * List files under a directory without following symlinked directories out
+ * of the tree, sorted for deterministic output.
+ * @param {string} directory - Directory to walk.
+ * @param {(file: string) => boolean} predicate - Filter on absolute paths.
+ * @returns {string[]} Matching absolute paths, sorted.
+ */
+export function listFiles(directory, predicate) {
+  if (!fs.existsSync(directory)) return [];
+  const found = [];
+  const stack = [directory];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile() && predicate(full)) found.push(full);
+    }
+  }
+  return found.sort();
+}
+
+/**
+ * Split one tag line into bare tag names.
+ * @param {string} trimmed - A trimmed source line beginning with `@`.
+ * @returns {string[]} Tag names without their leading `@`.
+ */
+function tagsOf(trimmed) {
+  return trimmed
+    .split(/\s+/)
+    .filter(token => token.startsWith("@"))
+    .map(token => token.slice(1))
+    .filter(Boolean);
+}
+
+/**
+ * Bucket a scenario's pending tags into the contract's categories.
+ * @param {readonly string[]} tags - Raw tag names.
+ * @param {ReadonlySet<string>} platforms - The project's declared platform vocabulary.
+ * @returns {object} Categorized tags, including tracker-shaped references.
+ */
+function categorize(tags, platforms) {
+  const trackers = [];
+  for (const tag of tags) {
+    const reference = parseTrackerTag(tag);
+    if (reference) trackers.push({ tag, ...reference });
+  }
+  return {
+    ids: tags.filter(tag => ID_PATTERN.test(tag)),
+    platforms: tags.filter(tag => platforms.has(tag)),
+    lifecycle: tags.filter(tag => LIFECYCLE.has(tag)),
+    provenance: tags.filter(tag => PROVENANCE_PATTERN.test(tag)),
+    trackers,
+  };
+}
+
+/**
+ * Parse one `.feature` source into scenarios.
+ *
+ * Tags accumulate until a `Feature:` or `Scenario:` consumes them, matching
+ * Gherkin's own tag scoping. `Scenario Outline` is treated as one scenario:
+ * the contract counts behaviors, not example rows.
+ * @param {string} source - File contents.
+ * @param {string} file - Repo-relative path, for error locations.
+ * @param {ReadonlySet<string>} platforms - The project's declared platform vocabulary.
+ * @returns {object[]} Parsed scenarios in source order.
+ */
+export function parseFeatureSource(source, file, platforms) {
+  const scenarios = [];
+  const lines = source.split(/\r?\n/);
+  let feature = null;
+  let pending = [];
+  let current = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
+    if (trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith("@")) {
+      pending.push(...tagsOf(trimmed));
+      continue;
+    }
+    const featureMatch = /^Feature:\s*(.+)$/.exec(trimmed);
+    if (featureMatch) {
+      feature = featureMatch[1].trim();
+      pending = [];
+      current = null;
+      continue;
+    }
+    const scenarioMatch = /^Scenario(?: Outline| Template)?:\s*(.+)$/.exec(
+      trimmed
+    );
+    if (scenarioMatch) {
+      const grouped = categorize(pending, platforms);
+      current = {
+        id: grouped.ids[0] ?? null,
+        name: scenarioMatch[1].trim(),
+        feature: feature ?? "Unknown feature",
+        file,
+        line: index + 1,
+        tags: [...pending],
+        ...grouped,
+        required: grouped.lifecycle.length === 0,
+        primarySteps: [],
+      };
+      scenarios.push(current);
+      pending = [];
+      continue;
+    }
+    const step = /^(Given|When|Then)\b/.exec(trimmed);
+    if (step && current) current.primarySteps.push(step[1]);
+  }
+  return scenarios;
+}
+
+/**
+ * Load every scenario declared under `bdd/features`.
+ * @param {string} root - Repo root.
+ * @param {ReadonlySet<string>} platforms - The project's declared platform vocabulary.
+ * @returns {object[]} Every parsed scenario, in stable file order.
+ */
+export function loadScenarios(root, platforms) {
+  const featureRoot = path.join(root, "bdd", "features");
+  return listFiles(featureRoot, file => file.endsWith(".feature")).flatMap(
+    file =>
+      parseFeatureSource(
+        fs.readFileSync(file, "utf8"),
+        posix(path.relative(root, file)),
+        platforms
+      )
+  );
+}
+
+/**
+ * Extract the scenario IDs present in a raw set of feature sources.
+ *
+ * Used against a base revision to detect scenarios deleted rather than
+ * `@superseded` — the denominator-gaming move the contract forbids.
+ * @param {readonly string[]} sources - Feature file contents.
+ * @returns {Set<string>} Every `BDD-*` ID found.
+ */
+export function scenarioIdsIn(sources) {
+  const ids = new Set();
+  for (const source of sources) {
+    for (const line of source.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("@")) continue;
+      for (const tag of tagsOf(trimmed)) if (ID_PATTERN.test(tag)) ids.add(tag);
+    }
+  }
+  return ids;
+}

package/expo/copy-overwrite/scripts/bdd/render.mjs

@@ -0,0 +1,170 @@
+/**
+ * Markdown rendering for the BDD burndown.
+ *
+ * The prose here is load-bearing: it is the only place a reader learns that
+ * the headline percentage is traceability, not execution and not a pass
+ * rate. Do not shorten it into a bare number.
+ *
+ * @module scripts/bdd/render
+ */
+
+/**
+ * Format a coverage figure, refusing to print "100%" for an empty
+ * denominator — a platform with no obligations has no coverage to report,
+ * and a bare 100% there is the exact false headline this gate exists to
+ * prevent.
+ * @param {object} value - A covered/total/percentage summary.
+ * @returns {string} Cell text.
+ */
+const fmt = value =>
+  value.total === 0
+    ? "n/a (no obligations)"
+    : `${value.covered}/${value.total} (${value.percentage.toFixed(1)}%)`;
+
+/**
+ * Render the per-platform traceability table.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown table.
+ */
+function platformTable(report) {
+  const rows = Object.entries(report.traceability.byPlatform)
+    .map(([platform, value]) => `| ${platform} | ${fmt(value)} |`)
+    .join("\n");
+  return `| Platform | Obligations with mapped automation |\n|---|---:|\n${rows}\n| **Overall** | **${fmt(report.traceability.overall)}** |`;
+}
+
+/**
+ * Render the execution section, which is deliberately empty-but-explicit
+ * when no run evidence was supplied.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown section body.
+ */
+function executionSection(report) {
+  const execution = report.execution;
+  if (!execution.supplied) {
+    return `**No execution evidence was supplied to this run.** ${execution.mappedTests} mapped tests exist; how many ran, and what they returned, is unknown here. Pass \`--results <file>\` with a runner result document to populate this section. Traceability without execution proves automation was written, never that it works.`;
+  }
+  const sources = execution.sources
+    .map(
+      source =>
+        `- \`${source.runner}\` run \`${source.runId ?? "unidentified"}\` (${source.resultCount} results, completed ${source.completedAt ?? "unknown"})`
+    )
+    .join("\n");
+  return `| Mapped tests | Executed | Passed | Failed | Skipped | Not run |\n|---:|---:|---:|---:|---:|---:|\n| ${execution.mappedTests} | ${execution.executed} | ${execution.passed} | ${execution.failed} | ${execution.skipped} | ${execution.notRun} |\n\nSources:\n\n${sources}`;
+}
+
+/**
+ * Render the waiver ledger.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown table.
+ */
+function waiverTable(report) {
+  const rows =
+    report.waived.entries
+      .map(
+        entry =>
+          `| ${entry.scenario} | ${entry.platforms.join(", ")} | ${entry.runner ?? "—"} | ${entry.owner ?? "**unowned**"} | ${entry.reason ?? "—"} | ${entry.ticket ?? "**none**"} | ${entry.expiresAt ?? "**never**"} |`
+      )
+      .join("\n") || "| — | — | — | — | None | — | — |";
+  return `| Scenario | Platforms | Runner | Owner | Reason | Ticket | Expires |\n|---|---|---|---|---|---|---|\n${rows}`;
+}
+
+/**
+ * Render the floor ratchet table.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown table.
+ */
+function floorTable(report) {
+  const rows = Object.entries(report.floor.byPlatform)
+    .map(
+      ([platform, value]) =>
+        `| ${platform} | ${value.floor === null ? "**unset**" : `${value.floor}%`} | ${value.actual}% | ${value.ok ? "ok" : "**below floor**"} |`
+    )
+    .join("\n");
+  return `| Platform | Committed floor | Current | Status |\n|---|---:|---:|---|\n${rows}`;
+}
+
+/**
+ * Group the remaining gaps by feature.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown sections.
+ */
+function gapSections(report) {
+  const grouped = new Map();
+  for (const gap of report.gaps) {
+    const entries = grouped.get(gap.feature) ?? new Map();
+    const entry = entries.get(gap.scenario) ?? {
+      name: gap.name,
+      platforms: [],
+    };
+    entry.platforms.push(gap.platform);
+    entries.set(gap.scenario, entry);
+    grouped.set(gap.feature, entries);
+  }
+  const sections = [...grouped.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([feature, entries]) => {
+      const rows = [...entries.entries()]
+        .map(
+          ([id, value]) =>
+            `| ${id} | ${value.name} | ${value.platforms.sort().join(", ")} |`
+        )
+        .join("\n");
+      return `### ${feature}\n\n| Scenario | Behavior with no mapped proof | Platforms |\n|---|---|---|\n${rows}`;
+    });
+  return (
+    sections.join("\n\n") ||
+    "None. Every required, non-waived obligation has aligned automation mapped to it."
+  );
+}
+
+/**
+ * Render the whole burndown document.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown document.
+ */
+export function renderBurndown(report) {
+  return `# BDD behavior contract — coverage burndown
+
+Generated from \`bdd/features/*.feature\` and \`bdd/coverage-map.json\` as of ${report.asOf ?? "an unrecorded date"}.
+Regenerated by \`node scripts/check-bdd-coverage.mjs --write\`; never hand-edited.
+
+## What each number means
+
+This document reports five different facts and never merges them:
+
+1. **Declared** — behaviors written as Gherkin scenarios. ${report.scenarios.declared} total, ${report.scenarios.required} in the denominator, ${report.scenarios.excluded} excluded (${report.scenarios.blocked} blocked, ${report.scenarios.referenceOnly} reference-only, ${report.scenarios.superseded} superseded).
+2. **Traceability coverage** — required obligations with aligned automation mapped and their evidence string still present. **This is not execution coverage and not a pass rate.** A mapped test that fails on every run still counts here.
+3. **Execution** — how many of those mapped tests actually ran in a supplied run.
+4. **Results** — what those runs returned: pass, fail, skip.
+5. **Waivers** — obligations deliberately outside the denominator. A waiver is a dated IOU with an owner and a retiring ticket; it is never coverage.
+
+## Traceability coverage
+
+${platformTable(report)}
+
+## Execution
+
+${executionSection(report)}
+
+## Coverage floor (ratchet)
+
+The committed floor may rise and may never fall. Lowering it requires a \`coverageFloorBaseline\` record naming the exact change plus the maintainer-applied \`bdd-floor-baseline\` label — two artifacts one author cannot produce alone.
+
+${floorTable(report)}
+
+## Waived obligations
+
+${report.waived.note}
+
+${waiverTable(report)}
+
+## Traceability to work items
+
+${report.trackers.scenariosWithTag} of ${report.scenarios.declared} scenarios carry a tracker tag; ${report.trackers.scenariosWithoutTag} do not. Tags are validated for syntax and against this repo's declared trackers; the gate never contacts a tracker, so an unreachable issue can never block a merge.
+
+## Required obligations with no mapped proof
+
+${gapSections(report)}
+`;
+}