explico 0.8.0 → 0.11.0

package/dist/compiler/manifest.js

@@ -30,6 +30,10 @@ import {
 import {
   validateDiagrams
 } from "../reference/diagrams-validate.js";
+import {
+  validateExamples
+} from "../reference/examples-validate.js";
+import { validateFolds } from "../reference/folds-validate.js";
 import {
   validateKnowledgeChecks
 } from "../reference/knowledge-checks-validate.js";
@@ -44,8 +48,21 @@ import {
   gateProseNotation,
   gateProseNotationInAssessments
 } from "../reference/gate-prose-notation.js";
+import {
+  gateMathPunctuation,
+  gateMathPunctuationInAssessments
+} from "../reference/gate-math-punctuation.js";
 import { gateAbbreviations } from "../reference/gate-abbreviations.js";
+import { gateCourseRules } from "../reference/gate-course-rules.js";
 import { gateHeadingLength } from "../reference/gate-heading-length.js";
+import { gateHeadingStructure } from "../reference/gate-heading-structure.js";
+import { gatePartPages } from "../reference/gate-part-pages.js";
+import {
+  scanSectionHeadings,
+  scanTitledBlocks
+} from "../reference/sections.mjs";
+import { knowledgeCheckAnchorId } from "../reference/knowledge-checks.mjs";
+import { validateSectionRefs } from "../reference/sections-validate.js";
 import {
   splitMixedContent
 } from "../reference/mixed-content.js";
@@ -55,9 +72,22 @@ import { formulaGlyphScope } from "../reference/gloss.js";
 import { resolveReferenceId } from "../reference/references.js";
 import {
   coursePartsOf,
+  normalizeBlockLabels,
   normalizeLessonExports,
-  normalizeDisclosureDefaults
+  normalizeDisclosure,
+  normalizeNumbering
 } from "./course-config.js";
+import {
+  disabledCodes,
+  dropDisabled,
+  partPageLimits,
+  resolveRules,
+  rulesSnapshot
+} from "../rules/settings.js";
+import {
+  applyWaivers,
+  collectWaivers
+} from "../rules/waivers.js";
 import {
   resolveKnowledgeVersion
 } from "./knowledge-version.js";
@@ -67,6 +97,7 @@ import {
   loadNotationDefinitions,
   loadNotationRegistryInput,
   loadNotationSpecs,
+  loadPartOverviews,
   loadSourceRecords
 } from "./collections.js";
 import {
@@ -75,7 +106,7 @@ import {
   isLessonSlug,
   lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 16;
+const MANIFEST_SCHEMA_VERSION = 24;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");
@@ -178,6 +209,16 @@ function lessonNotationBundle(bundle, definitionsById, resolution, cardsByKey) {
     resolution: [...resolution]
   };
 }
+function studyMinutesRange(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return { min: value, max: value };
+  }
+  if (Array.isArray(value) && value.length === 2 && value.every((entry) => typeof entry === "number" && entry > 0)) {
+    const [min, max] = value;
+    return min <= max ? { min, max } : { min: max, max: min };
+  }
+  return void 0;
+}
 function lessonFrontmatterById() {
   const base = join(CONTENT_ROOT, "docs");
   const result = /* @__PURE__ */ new Map();
@@ -193,9 +234,11 @@ function lessonFrontmatterById() {
       if (!isLessonSlug(slug)) continue;
       const id = slug.replace(/\.(md|mdx)$/, "").replace(/\//g, ".");
       const data = parseFrontmatter(readFileSync(path, "utf8")).frontmatter ?? {};
+      const studyMinutes = studyMinutesRange(data.studyMinutes);
       result.set(id, {
         title: typeof data.title === "string" ? data.title : id,
-        description: typeof data.description === "string" ? data.description : ""
+        description: typeof data.description === "string" ? data.description : "",
+        ...studyMinutes === void 0 ? {} : { studyMinutes }
       });
     }
   };
@@ -208,6 +251,10 @@ async function compileManifest(courseConfig) {
       "course.config.ts is missing a complete `about` block (required since explico 0.3.0): `about: { version, authors: [{ name }], disclaimer, materialName?, summary?, changelogHref? }`. See docs/authoring/migrating.md (\xA7 0.2.x \u2192 0.3.0) in the installed package."
     );
   }
+  const rules = resolveRules(courseConfig);
+  const off = disabledCodes(rules);
+  const numberingSettings = normalizeNumbering(courseConfig);
+  const blockLabels = normalizeBlockLabels(courseConfig);
   const [catalog, notationInput, abbreviationsInput] = await Promise.all([
     loadCurriculumCatalog(),
     loadNotationRegistryInput(),
@@ -230,6 +277,10 @@ async function compileManifest(courseConfig) {
   const assessmentsInput = catalog.assessments;
   const curriculumIssues = validateCurriculum(catalog);
   const alignmentIssues = validateNotationAlignment(registry, catalog);
+  const mathEndAbbreviations = {
+    allow: rules.strings("N12", "allow"),
+    deny: rules.strings("N12", "deny")
+  };
   const mathIssues = [
     ...gateContentMath({
       notationInput,
@@ -239,14 +290,34 @@ async function compileManifest(courseConfig) {
         assessmentIds: lesson.assessments
       }))
     }),
-    ...gateProseNotation(notationInput.lessons),
-    ...gateProseNotationInAssessments(assessmentsInput),
-    ...gateAbbreviations({
+    ...rules.isEnabled("N9") ? [
+      ...gateProseNotation(notationInput.lessons, {
+        allowSpelledUnits: rules.strings("N9", "allow")
+      }),
+      ...gateProseNotationInAssessments(assessmentsInput, {
+        allowSpelledUnits: rules.strings("N9", "allow")
+      })
+    ] : [],
+    ...rules.isEnabled("N12") ? [
+      ...gateMathPunctuation(notationInput.lessons, mathEndAbbreviations),
+      ...gateMathPunctuationInAssessments(assessmentsInput, mathEndAbbreviations)
+    ] : [],
+    ...rules.isEnabled("N14") ? gateAbbreviations({
       notationInput,
       abbreviations: abbreviationsInput,
-      courseAbbreviations: courseConfig.abbreviations
+      courseAbbreviations: rules.settings("N14")
+    }) : [],
+    ...rules.isEnabled("S1") ? gateHeadingLength(notationInput.lessons, {
+      maxLength: rules.number("S1", "maxLength")
+    }) : [],
+    ...gateHeadingStructure(notationInput.lessons, {
+      levels: rules.isEnabled("S6"),
+      adjacency: rules.isEnabled("S7")
     }),
-    ...gateHeadingLength(notationInput.lessons)
+    // The course's own rules (`courseRules`): one pass for every enabled `X`
+    // rule that carries a `forbid` pattern. A disabled one, and a guide rule
+    // with no pattern, do no work here.
+    ...gateCourseRules(notationInput.lessons, rules.course)
   ];
   const notationLessonById = new Map(
     notationInput.lessons.map((lesson) => [lesson.lessonId, lesson])
@@ -294,15 +365,48 @@ async function compileManifest(courseConfig) {
   );
   const frontmatterById = lessonFrontmatterById();
   const lessonSlugs = [...notationInput.lessons].map((lesson) => lesson.lessonId.replace(/\./g, "/")).sort();
+  const configuredParts = coursePartsOf(courseConfig);
+  const overviewPages = loadPartOverviews(configuredParts);
+  const overviewByDir = new Map(overviewPages.map((page) => [page.dir, page]));
+  if (rules.isEnabled("S2")) {
+    mathIssues.push(
+      ...gatePartPages(
+        overviewPages.map((page) => ({
+          ...page,
+          ordinal: configuredParts.findIndex((part) => part.dir === page.dir) + 1
+        })),
+        partPageLimits(rules)
+      )
+    );
+  }
+  const waiverDiagnostics = [];
+  const waiverRules = { courseRules: rules.course };
+  const waivers = notationInput.lessons.flatMap((lesson) => {
+    const collected = collectWaivers(lesson, waiverRules);
+    waiverDiagnostics.push(...collected.diagnostics);
+    return collected.waivers;
+  });
+  const waived = applyWaivers(mathIssues, waivers, waiverRules);
+  mathIssues.splice(0, mathIssues.length, ...waived.kept);
+  waiverDiagnostics.push(...waived.unused);
   const sidebar = buildSidebar(
     catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
     lessonSlugs,
-    coursePartsOf(courseConfig)
+    configuredParts.map((part) => ({
+      ...part,
+      ...overviewByDir.has(part.dir) ? { overviewLink: `/${part.dir}/` } : {}
+    })),
+    {
+      floatIndex: [".mdx", ".md"].some(
+        (extension) => existsSync(join(CONTENT_ROOT, "docs", `figures-and-tables${extension}`))
+      )
+    }
   );
   const bodyByLessonId = new Map(
     notationInput.lessons.map((lesson) => [lesson.lessonId, lesson.body])
   );
   const placementByLessonId = /* @__PURE__ */ new Map();
+  const chapterScoped = numberingSettings.floats === "chapter";
   let partCursor = 0;
   for (const group of sidebar) {
     const lessonIds = group.items.filter((item) => typeof item === "string").map(lessonIdFromSlug);
@@ -313,23 +417,88 @@ async function compileManifest(courseConfig) {
       tables: 0,
       figures: 0,
       diagrams: 0,
-      checks: 0
+      checks: 0,
+      examples: 0
     };
     let chapterCursor = 0;
     for (const lessonId of lessonIds) {
       const body = bodyByLessonId.get(lessonId) ?? "";
+      const chapter = ++chapterCursor;
       placementByLessonId.set(lessonId, {
         part: partCursor,
-        chapter: ++chapterCursor,
-        numbering: { ...used }
+        chapter,
+        numbering: chapterScoped ? {
+          prefix: `${partCursor}.${chapter}`,
+          equations: 0,
+          tables: 0,
+          figures: 0,
+          diagrams: 0,
+          checks: 0,
+          examples: 0
+        } : { prefix: String(partCursor), ...used }
       });
       used.equations += countDisplayEquations(body);
       used.tables += countKeyedJsxFloats(body, { tagName: "Table" });
       used.figures += countKeyedJsxFloats(body, { tagName: "Figure" });
       used.diagrams += countKeyedJsxFloats(body, { tagName: "Diagram" });
       used.checks += lessonMetaById.get(lessonId)?.assessments.length ?? 0;
+      used.examples += countKeyedJsxFloats(body, { tagName: "CompactExamples" });
     }
   }
+  const headingsByLessonId = new Map(
+    notationInput.lessons.map((lesson) => {
+      const placement = placementByLessonId.get(lesson.lessonId);
+      return [
+        lesson.lessonId,
+        scanSectionHeadings(lesson.body, {
+          ...placement ? { prefix: `${placement.part}.${placement.chapter}` } : {},
+          depth: numberingSettings.sections.depth
+        })
+      ];
+    })
+  );
+  mathIssues.push(
+    ...validateSectionRefs(
+      notationInput.lessons.map((lesson) => ({
+        slug: lesson.lessonId.replace(/\./g, "/"),
+        file: lesson.source.file,
+        body: lesson.body,
+        ...lesson.bodyLine === void 0 ? {} : { bodyLine: lesson.bodyLine },
+        headingSlugs: (headingsByLessonId.get(lesson.lessonId) ?? []).map(
+          (heading) => heading.slug
+        )
+      }))
+    )
+  );
+  const manifestParts = configuredParts.map((part, index) => {
+    const overview = overviewByDir.get(part.dir);
+    const lessonIds = [...placementByLessonId].filter(([lessonId]) => lessonId.startsWith(`${part.dir}.`)).sort(([, a], [, b]) => a.chapter - b.chapter).map(([lessonId]) => lessonId);
+    const chapterMinutes = lessonIds.map(
+      (lessonId) => frontmatterById.get(lessonId)?.studyMinutes
+    );
+    const studyMinutes = chapterMinutes.length > 0 && chapterMinutes.every((range) => range !== void 0) ? chapterMinutes.reduce(
+      (total, range) => ({
+        min: total.min + range.min,
+        max: total.max + range.max
+      }),
+      { min: 0, max: 0 }
+    ) : void 0;
+    return {
+      dir: part.dir,
+      label: part.label,
+      ordinal: index + 1,
+      link: `/${part.dir}/`,
+      lessons: lessonIds,
+      ...studyMinutes === void 0 ? {} : { studyMinutes },
+      ...overview ? {
+        overview: {
+          title: overview.title,
+          file: overview.file,
+          ...overview.description === void 0 ? {} : { description: overview.description }
+        }
+      } : {}
+    };
+  });
   const floatInputs = (kind) => notationInput.lessons.map((lesson) => {
     const placement = placementByLessonId.get(lesson.lessonId);
     return {
@@ -339,40 +508,37 @@ async function compileManifest(courseConfig) {
       body: lesson.body,
       ...placement ? {
         numbering: {
-          prefix: placement.part,
+          prefix: placement.numbering.prefix,
           offset: placement.numbering[kind]
         }
       } : {}
     };
   });
+  const floatsBySlug = (labels) => {
+    const bySlug = /* @__PURE__ */ new Map();
+    for (const { slug, key, number, short, caption } of labels) {
+      const list = bySlug.get(slug) ?? [];
+      list.push({
+        key,
+        number,
+        ...short === void 0 ? {} : { short },
+        ...caption === void 0 ? {} : { caption }
+      });
+      bySlug.set(slug, list);
+    }
+    return bySlug;
+  };
   const equationValidation = validateEquations(floatInputs("equations"));
-  const equationsBySlug = new Map(
-    Object.entries(equationValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number }))
-    ])
-  );
+  const equationsBySlug = floatsBySlug(equationValidation.labels);
   const tableValidation = validateTables(floatInputs("tables"));
-  const tablesBySlug = new Map(
-    Object.entries(tableValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number }))
-    ])
-  );
+  const tablesBySlug = floatsBySlug(tableValidation.labels);
   const figureValidation = validateFigures(floatInputs("figures"));
-  const figuresBySlug = new Map(
-    Object.entries(figureValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number }))
-    ])
-  );
+  const figuresBySlug = floatsBySlug(figureValidation.labels);
   const diagramValidation = validateDiagrams(floatInputs("diagrams"));
-  const diagramsBySlug = new Map(
-    Object.entries(diagramValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number }))
-    ])
-  );
+  const diagramsBySlug = floatsBySlug(diagramValidation.labels);
+  const exampleValidation = validateExamples(floatInputs("examples"));
+  const examplesBySlug = floatsBySlug(exampleValidation.labels);
+  const foldValidation = validateFolds(floatInputs("figures"));
   const checkValidation = validateKnowledgeChecks(
     notationInput.lessons.map((lesson) => {
       const placement = placementByLessonId.get(lesson.lessonId);
@@ -384,19 +550,49 @@ async function compileManifest(courseConfig) {
         assessmentIds: lessonMetaById.get(lesson.lessonId)?.assessments ?? [],
         ...placement ? {
           numbering: {
-            prefix: placement.part,
+            prefix: placement.numbering.prefix,
             offset: placement.numbering.checks
           }
         } : {}
       };
     })
   );
+  const checkTitleById = new Map(
+    assessmentsInput.map((assessment) => [assessment.id, assessment.title])
+  );
   const checksBySlug = new Map(
     Object.entries(checkValidation.numbersBySlug).map(([slug, table]) => [
       slug,
-      Object.entries(table).map(([key, number]) => ({ key, number }))
+      Object.entries(table).map(([key, number]) => {
+        const title = checkTitleById.get(key);
+        return { key, number, ...title === void 0 ? {} : { title } };
+      })
     ])
   );
+  const titledBlocksFor = (lessonId) => {
+    const slug = lessonId.replace(/\./g, "/");
+    const body = bodyByLessonId.get(lessonId) ?? "";
+    const headings = headingsByLessonId.get(lessonId) ?? [];
+    const checks = checksBySlug.get(slug) ?? [];
+    const examples = examplesBySlug.get(slug) ?? [];
+    return scanTitledBlocks(body, ["AssessmentSet", "CompactExamples"]).flatMap(
+      (block) => {
+        const after = headings[block.heading]?.slug;
+        const place = after === void 0 ? {} : { after };
+        if (block.name === "CompactExamples") {
+          const set = examples.find((example) => example.key === block.id);
+          return set?.short ? [{ kind: "example", key: set.key, anchor: `ex-${set.key}`, title: set.short, ...place }] : [];
+        }
+        return checks.filter((check) => block.id === void 0 || check.key === block.id).map((check) => ({
+          kind: "check",
+          key: check.key,
+          anchor: knowledgeCheckAnchorId(check.key),
+          title: check.title ?? check.key,
+          ...place
+        }));
+      }
+    );
+  };
   const rawFloatDiagnostics = validateRawFloats(
     notationInput.lessons.map((lesson) => ({
       lessonId: lesson.lessonId,
@@ -424,27 +620,33 @@ async function compileManifest(courseConfig) {
       part: placementByLessonId.get(id)?.part ?? 0,
       chapter: placementByLessonId.get(id)?.chapter ?? 0,
       numbering: placementByLessonId.get(id)?.numbering ?? {
+        prefix: "",
         equations: 0,
         tables: 0,
         figures: 0,
         diagrams: 0,
-        checks: 0
+        checks: 0,
+        examples: 0
       },
+      headings: headingsByLessonId.get(id) ?? [],
       file: notationLesson.source.file,
       title: frontmatter.title,
       description: frontmatter.description,
+      ...frontmatter.studyMinutes === void 0 ? {} : { studyMinutes: frontmatter.studyMinutes },
       status: meta.status,
       teaches: [...teaches],
       requires: [...meta.requires],
       assumptions: [...meta.assumptions],
       assessments: [...meta.assessments],
       knowledgeChecks: checksBySlug.get(id.replace(/\./g, "/")) ?? [],
+      titledBlocks: titledBlocksFor(id),
       sources: deriveSources(notationLesson.body),
       citations: lessonCitations(notationLesson.body),
       equations: equationsBySlug.get(id.replace(/\./g, "/")) ?? [],
       tables: tablesBySlug.get(id.replace(/\./g, "/")) ?? [],
       figures: figuresBySlug.get(id.replace(/\./g, "/")) ?? [],
       diagrams: diagramsBySlug.get(id.replace(/\./g, "/")) ?? [],
+      examples: examplesBySlug.get(id.replace(/\./g, "/")) ?? [],
       prereqEdges: sortEdges(
         teaches.flatMap(
           (to) => (prerequisitesById.get(to) ?? []).filter((from) => !teaches.includes(from)).map((from) => ({ from, to }))
@@ -470,8 +672,9 @@ async function compileManifest(courseConfig) {
     catalog,
     lintIgnore: loadLintIgnore(),
     conventions: courseConfig.conventions,
-    ...courseConfig.operators === void 0 ? {} : { operators: courseConfig.operators },
-    ...courseConfig.romanLabels === void 0 ? {} : { romanLabels: courseConfig.romanLabels }
+    operators: rules.settings("N8"),
+    romanLabels: rules.settings("N10"),
+    accents: rules.settings("N22")
   });
   const rawNotation = [...loadNotationDefinitions()].sort(
     (a, b) => String(a.key).localeCompare(String(b.key))
@@ -520,7 +723,9 @@ async function compileManifest(courseConfig) {
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
-    disclosureDefaults: normalizeDisclosureDefaults(courseConfig),
+    disclosure: normalizeDisclosure(courseConfig),
+    numbering: numberingSettings,
+    blockLabels,
     about,
     notation: {
       definitions: registry.definitions,
@@ -534,6 +739,7 @@ async function compileManifest(courseConfig) {
     tracks,
     abbreviations,
     sidebar,
+    parts: manifestParts,
     lessons,
     prereqEdges,
     equations: {
@@ -556,20 +762,29 @@ async function compileManifest(courseConfig) {
       labels: checkValidation.labels,
       numbersBySlug: checkValidation.numbersBySlug
     },
+    examples: {
+      labels: exampleValidation.labels,
+      numbersBySlug: exampleValidation.numbersBySlug
+    },
     assessmentContent,
+    rules: rulesSnapshot(rules),
     diagnostics: {
-      curriculum: curriculumIssues,
-      notation: registry.diagnostics,
-      alignment: alignmentIssues,
-      math: mathIssues,
-      consistency: consistencyIssues,
-      equations: equationValidation.diagnostics,
-      tables: tableValidation.diagnostics,
-      figures: figureValidation.diagnostics,
-      diagrams: diagramValidation.diagnostics,
-      checks: checkValidation.diagnostics,
-      knowledge: knowledge.diagnostics,
-      rawFloats: rawFloatDiagnostics
+      curriculum: dropDisabled(curriculumIssues, off),
+      notation: dropDisabled(registry.diagnostics, off),
+      alignment: dropDisabled(alignmentIssues, off),
+      math: dropDisabled(mathIssues, off),
+      consistency: dropDisabled(consistencyIssues, off),
+      equations: dropDisabled(equationValidation.diagnostics, off),
+      tables: dropDisabled(tableValidation.diagnostics, off),
+      figures: dropDisabled(figureValidation.diagnostics, off),
+      diagrams: dropDisabled(diagramValidation.diagnostics, off),
+      checks: dropDisabled(checkValidation.diagnostics, off),
+      examples: dropDisabled(exampleValidation.diagnostics, off),
+      folds: dropDisabled(foldValidation.diagnostics, off),
+      knowledge: dropDisabled(knowledge.diagnostics, off),
+      rawFloats: dropDisabled(rawFloatDiagnostics, off),
+      config: rules.diagnostics,
+      waivers: waiverDiagnostics
     },
     hashes
   };

package/dist/compiler/resolution-report.d.ts

@@ -1,7 +1,9 @@
 import { Manifest } from './manifest.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
-import './course-config.js';
+import '../course-config-Dsnri9Tk.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
 import './collections.js';
 import '../reference/types.js';
 import '../reference/lint-ignore.js';
@@ -10,11 +12,14 @@ import '../reference/tables-validate.js';
 import '../reference/keyed-float-validate.js';
 import '../reference/figures-validate.js';
 import '../reference/diagrams-validate.js';
+import '../reference/examples-validate.js';
+import '../reference/folds-validate.js';
 import '../reference/knowledge-checks-validate.js';
 import '../reference/raw-floats-validate.js';
 import '../reference/gate-math.js';
 import '../reference/mixed-content.js';
 import '../reference/gloss.js';
+import '../rules/waivers.js';
 import './knowledge-version.js';
 import './lesson-derivation.js';