explico 0.8.0 → 0.11.1

package/dist/rules/in-effect.js

@@ -0,0 +1,142 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ELEMENTS,
+  enforcementOf,
+  invariants,
+  rules as catalogRules
+} from "./catalog.js";
+import { courseRuleEntry } from "./course-rules.js";
+import { isWaivable } from "./waivers.js";
+const DOC_ROOT = "../node_modules/explico/docs/authoring";
+function docLink(entry) {
+  return entry.kind === "rule" && entry.source === "course" ? entry.doc : `${DOC_ROOT}/${entry.doc}`;
+}
+function liveRules(input) {
+  return [...catalogRules(), ...input.rules.course.map(courseRuleEntry)];
+}
+function enforcementLabel(entry) {
+  return entry.kind === "rule" && entry.locked !== void 0 ? "locked" : enforcementOf(entry);
+}
+function matches(entry, filter) {
+  if (filter.elements && !entry.elements.some((e) => filter.elements.includes(e))) return false;
+  if (filter.enforcement && enforcementLabel(entry) !== filter.enforcement) return false;
+  return true;
+}
+function rulesInEffect(input, filter = {}) {
+  const off = new Set(input.rules.disabled);
+  const entries = [...liveRules(input), ...invariants()];
+  return entries.filter((entry) => matches(entry, filter)).map((entry) => ({
+    id: entry.id,
+    kind: entry.kind,
+    source: entry.kind === "rule" && entry.source === "course" ? "course" : "engine",
+    title: entry.title,
+    elements: entry.elements,
+    enforcement: enforcementLabel(entry),
+    enabled: !off.has(entry.id),
+    waivable: entry.kind === "rule" && isWaivable(entry),
+    codes: entry.checks.map((c) => c.code),
+    settings: entry.kind === "rule" ? input.rules.settings[entry.id] ?? {} : {},
+    summary: entry.summary,
+    doc: docLink(entry)
+  }));
+}
+function settingValue(value) {
+  if (!Array.isArray(value)) return JSON.stringify(value) ?? String(value);
+  if (value.length === 0) return "[]";
+  const items = value.map(
+    (item) => typeof item === "string" ? `\`${item}\`` : JSON.stringify(item)
+  );
+  return `[${items.join(", ")}]`;
+}
+function settingsText(rule, settings) {
+  const specs = rule.settings ?? [];
+  if (specs.length === 0) return "";
+  return ` (${specs.map((s) => `${s.key} = ${settingValue(settings[s.key])}`).join(", ")})`;
+}
+function ruleLine(rule, settings) {
+  const label = enforcementLabel(rule);
+  const codes = rule.checks.map((c) => `\`${c.code}\``).join(", ");
+  const head = [
+    `**${rule.id}**`,
+    rule.source === "course" ? "course" : "",
+    label,
+    codes,
+    isWaivable(rule) ? "waivable" : ""
+  ].filter(Boolean).join(" \xB7 ");
+  const also = rule.elements.length > 1 ? ` (also: ${rule.elements.slice(1).join(", ")})` : "";
+  const unchecked = rule.unchecked ? ` Not checked by the build: ${rule.unchecked}` : "";
+  return `- ${head}${also} \u2014 ${rule.summary}${settingsText(rule, settings)}${unchecked} \u2192 [${rule.doc}](${docLink(rule)})`;
+}
+function renderRulesInEffect(input, filter = {}) {
+  const off = new Set(input.rules.disabled);
+  const on = liveRules(input).filter((r) => !off.has(r.id));
+  const ours = on.filter((r) => r.source === "course").length;
+  const locked = on.filter((r) => r.locked !== void 0).map((r) => r.id);
+  const filtered = filter.elements || filter.enforcement;
+  const visible = on.filter((r) => matches(r, filter));
+  const lines = [];
+  lines.push(
+    `# Rules in effect \u2014 ${input.about.material.name} (knowledge ${input.about.knowledge.version}, ${input.about.engine.name} ${input.about.engine.version})`,
+    "",
+    "Generated by `pnpm validate:content` (and `pnpm content rules`) from the rule",
+    "catalog and `rules` / `courseRules` in `course.settings.json`. Do not edit. Read this before",
+    "drafting, and open a rule page only when it is listed here and you need the",
+    "example: a rule absent from this page is either off for this course or does",
+    "not exist, and is neither applied nor flagged in review.",
+    "",
+    `${on.length} rules on (${locked.length} locked${ours === 0 ? "" : `, ${ours} this course's own`}), ${off.size} off, ${invariants().length} invariants always on.` + (filtered ? ` Filtered: ${[
+      filter.elements ? `element ${filter.elements.join(", ")}` : "",
+      filter.enforcement ? `enforcement ${filter.enforcement}` : ""
+    ].filter(Boolean).join("; ")} \u2014 ${visible.length} shown.` : ""),
+    "",
+    "A line is `ID \xB7 enforcement \xB7 codes \u2014 what to do (settings in effect) \u2192 full",
+    "text`. **course**: this course wrote the rule in `courseRules` in",
+    "`course.settings.json`, where it can be edited; the `X` area is reserved for",
+    "them. **script**: the build reports every violation under those codes.",
+    "**partial**: the build reports the codes; the rest is on you. **guide**: nothing",
+    "runs; it is on you. **locked**: script, and the course cannot turn it off.",
+    "**waivable**: break it at one place with `{/* explico-allow <ID>[, <ID>]: <reason> */}`",
+    "on its own line above the block (a paragraph, heading, or tag; a blank line",
+    "ends it) \u2014 the reason is mandatory, and a waiver that silences nothing is a",
+    "warning. A finding without a line (a notation entry, a per-lesson count) is",
+    "silenced per key in `lint-ignore.yml` (`- <code>:<key> \u2014 <reason>`) instead."
+  );
+  for (const element of ELEMENTS) {
+    const here = visible.filter((r) => r.elements[0] === element);
+    if (here.length === 0) continue;
+    lines.push("", `## ${element}`, "");
+    for (const rule of here) lines.push(ruleLine(rule, input.rules.settings[rule.id] ?? {}));
+  }
+  const visibleInvariants = invariants().filter((i) => matches(i, filter));
+  lines.push("", "## Always on (invariants)", "");
+  if (visibleInvariants.length === 0) {
+    lines.push("- (none match the filter)");
+  }
+  for (const inv of visibleInvariants) {
+    const codes = inv.checks.map((c) => `\`${c.code}\``).join(", ");
+    lines.push(
+      `- **${inv.id}** (${inv.elements.join(", ")}) \u2014 ${inv.summary} Codes: ${codes}. \u2192 [${inv.doc}](${DOC_ROOT}/${inv.doc})`
+    );
+  }
+  lines.push("", "## Off", "");
+  lines.push(
+    off.size === 0 ? "- Nothing \u2014 every rule is on." : `- ${[...off].join(", ")} \u2014 turned off in \`course.settings.json\` (\`rules\`, or \`courseRules\` for an \`X\` rule). Do not apply them; do not flag them in review.`
+  );
+  lines.push("", "## Locked", "");
+  lines.push(`- ${locked.join(", ")} \u2014 cannot be turned off; listed above under their element.`);
+  return `${lines.join("\n")}
+`;
+}
+function writeRulesInEffect(input, root = process.cwd()) {
+  const dir = join(root, "build");
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, "rules-in-effect.md");
+  writeFileSync(path, renderRulesInEffect(input));
+  return path;
+}
+export {
+  renderRulesInEffect,
+  rulesInEffect,
+  writeRulesInEffect
+};