lens-content-processor 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,95 +1,165 @@
-import { flattenModule, flattenLens } from './flattener/index.js';
-import { parseModule } from './parser/module.js';
-import { parseCourse } from './parser/course.js';
-import { parseLearningOutcome } from './parser/learning-outcome.js';
-import { parseLens } from './parser/lens.js';
-import { parseWikilink, resolveWikilinkPath, findFileWithExtension, findSimilarFiles, formatSuggestion } from './parser/wikilink.js';
-import { validateUuids } from './validator/uuid.js';
-import { detectDuplicateSlugs } from './validator/duplicates.js';
-import { validateOutputIntegrity } from './validator/output-integrity.js';
-import { extractArticleExcerpt } from './bundler/article.js';
-import { extractVideoExcerpt } from './bundler/video.js';
-import { parseArticle } from './parser/article.js';
-import { parseVideoTranscript } from './parser/video-transcript.js';
-import { validateTimestamps } from './validator/timestamps.js';
-import { levenshtein } from './validator/field-typos.js';
-import { buildTierMap, checkTierViolation } from './validator/tier.js';
-export { checkTierViolation } from './validator/tier.js';
+import { flattenModule, flattenLens } from "./flattener/index.js";
+import { dedupeErrors } from "./dedupe-errors.js";
+import { populateCardModuleSlugs, resolveInlineLensModuleSlugs, } from "./flattener/resolve-text-links.js";
+import { parseModule, hasFieldBeforeSegmentHeaders } from "./parser/module.js";
+import { parseCourse } from "./parser/course.js";
+import { parseLearningOutcome, } from "./parser/learning-outcome.js";
+import { parseLens } from "./parser/lens.js";
+import { parseWikilink, resolveWikilinkPath, findFileWithExtension, findSimilarFiles, formatSuggestion, } from "./parser/wikilink.js";
+import { validateUuids } from "./validator/uuid.js";
+import { detectDuplicateSlugs, } from "./validator/duplicates.js";
+import { validateOutputIntegrity } from "./validator/output-integrity.js";
+import { extractArticleExcerpt } from "./bundler/article.js";
+import { extractVideoExcerpt, } from "./bundler/video.js";
+import { parseArticle } from "./parser/article.js";
+import { parseVideoTranscript } from "./parser/video-transcript.js";
+import { validateTimestamps } from "./validator/timestamps.js";
+import { levenshtein } from "./validator/field-typos.js";
+import { buildTierMap, checkTierViolation, } from "./validator/tier.js";
+import { validateCardModuleMembership } from "./validator/card-module-membership.js";
+export { checkTierViolation } from "./validator/tier.js";
+/**
+ * Recursively collect UUIDs from inline lens sections (including submodule children).
+ */
+function collectInlineLensUUIDs(sections, path, uuidEntries, errors) {
+    for (const section of sections) {
+        if (section.type === "lens") {
+            if (section.inlineLens) {
+                // Inline lens — id already validated in parseInlineLens
+                uuidEntries.push({
+                    uuid: section.fields.id,
+                    file: path,
+                    field: "section id",
+                });
+            }
+            else if (!hasFieldBeforeSegmentHeaders(section.body, "source", section.level) &&
+                !section.fields.id) {
+                // No section-level source:: and no id:: → missing required id
+                errors.push({
+                    file: path,
+                    line: section.line,
+                    message: `Inline Lens section '${section.title}' is missing required id:: field`,
+                    suggestion: "Add an id:: field with a UUID (e.g., id:: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)",
+                    severity: "error",
+                });
+            }
+            else if (section.fields.id) {
+                // Has id:: — collect UUID
+                uuidEntries.push({
+                    uuid: section.fields.id,
+                    file: path,
+                    field: "section id",
+                });
+            }
+        }
+        if (section.children) {
+            collectInlineLensUUIDs(section.children, path, uuidEntries, errors);
+        }
+    }
+}
+function collectLearningOutcomeTestUUIDs(learningOutcome, path, uuidEntries) {
+    if (learningOutcome.test) {
+        uuidEntries.push({
+            uuid: learningOutcome.test.id,
+            file: path,
+            field: "test section id",
+        });
+    }
+    for (const group of learningOutcome.submodules ?? []) {
+        if (group.test) {
+            uuidEntries.push({
+                uuid: group.test.id,
+                file: path,
+                field: "test section id",
+            });
+        }
+    }
+}
 /**
  * Validate lens excerpts by checking if source files exist and anchors/timestamps are valid.
+ * Iterates flat segments, using each segment's source field (set via inheritance in parseLens).
  */
 function validateLensExcerpts(lens, lensPath, files, tierMap) {
     const errors = [];
-    for (const section of lens.sections) {
-        // Skip sections without source (e.g., Text sections)
-        if (!section.source)
-            continue;
-        // Resolve the source wikilink to get the actual file path
-        const wikilink = parseWikilink(section.source);
-        if (!wikilink || wikilink.error)
-            continue;
-        const resolvedPath = resolveWikilinkPath(wikilink.path, lensPath);
-        const actualPath = findFileWithExtension(resolvedPath, files);
-        if (!actualPath) {
-            // Find similar files to suggest
-            const expectedDir = section.type.includes('article') ? 'articles' : 'video_transcripts';
-            const similarFiles = findSimilarFiles(resolvedPath, files, expectedDir);
-            const suggestion = formatSuggestion(similarFiles, lensPath) ?? 'Check that the file exists and the path is correct';
-            errors.push({
-                file: lensPath,
-                line: section.line,
-                message: `Source file not found: ${resolvedPath}`,
-                suggestion,
-                severity: 'error',
-            });
-            continue;
-        }
-        // Check tier violation (Lens → Article/Video)
-        if (tierMap) {
-            const childLabel = section.type.includes('article') ? 'article' : 'video transcript';
-            const parentTier = tierMap.get(lensPath) ?? 'production';
-            const childTier = tierMap.get(actualPath) ?? 'production';
-            const violation = checkTierViolation(lensPath, parentTier, actualPath, childTier, childLabel, section.line);
-            if (violation) {
-                errors.push(violation);
+    for (const segment of lens.segments) {
+        if (segment.type === "article" && segment.source) {
+            const wikilink = parseWikilink(segment.source);
+            if (!wikilink || wikilink.error)
                 continue;
-            }
-            if (childTier === 'ignored') {
+            const resolvedPath = resolveWikilinkPath(wikilink.path, lensPath);
+            const actualPath = findFileWithExtension(resolvedPath, files);
+            if (!actualPath) {
+                const similarFiles = findSimilarFiles(resolvedPath, files, "articles");
+                const suggestion = formatSuggestion(similarFiles, lensPath) ??
+                    "Check that the file exists and the path is correct";
+                errors.push({
+                    file: lensPath,
+                    message: `Source file not found: ${resolvedPath}`,
+                    suggestion,
+                    severity: "error",
+                });
                 continue;
             }
-        }
-        const sourceContent = files.get(actualPath);
-        // Validate article excerpts
-        if (section.type === 'article' || section.type === 'lens-article') {
-            for (const segment of section.segments) {
-                if (segment.type === 'article-excerpt') {
-                    const result = extractArticleExcerpt(sourceContent, segment.fromAnchor, segment.toAnchor, actualPath);
-                    if (result.error) {
-                        errors.push({ ...result.error, file: lensPath });
-                    }
+            if (tierMap) {
+                const parentTier = tierMap.get(lensPath) ?? "production";
+                const childTier = tierMap.get(actualPath) ?? "production";
+                const violation = checkTierViolation(lensPath, parentTier, actualPath, childTier, "article");
+                if (violation) {
+                    errors.push(violation);
+                    continue;
                 }
+                if (childTier === "ignored")
+                    continue;
+            }
+            const sourceContent = files.get(actualPath);
+            const result = extractArticleExcerpt(sourceContent, segment.fromAnchor, segment.toAnchor, actualPath);
+            if (result.error) {
+                errors.push({ ...result.error, file: lensPath });
             }
         }
-        // Validate video excerpts
-        if (section.type === 'video' || section.type === 'lens-video') {
-            // Look for corresponding .timestamps.json file
-            const timestampsPath = actualPath.replace(/\.md$/, '.timestamps.json');
+        else if (segment.type === "video" && segment.source) {
+            const wikilink = parseWikilink(segment.source);
+            if (!wikilink || wikilink.error)
+                continue;
+            const resolvedPath = resolveWikilinkPath(wikilink.path, lensPath);
+            const actualPath = findFileWithExtension(resolvedPath, files);
+            if (!actualPath) {
+                const similarFiles = findSimilarFiles(resolvedPath, files, "video_transcripts");
+                const suggestion = formatSuggestion(similarFiles, lensPath) ??
+                    "Check that the file exists and the path is correct";
+                errors.push({
+                    file: lensPath,
+                    message: `Source file not found: ${resolvedPath}`,
+                    suggestion,
+                    severity: "error",
+                });
+                continue;
+            }
+            if (tierMap) {
+                const parentTier = tierMap.get(lensPath) ?? "production";
+                const childTier = tierMap.get(actualPath) ?? "production";
+                const violation = checkTierViolation(lensPath, parentTier, actualPath, childTier, "video transcript");
+                if (violation) {
+                    errors.push(violation);
+                    continue;
+                }
+                if (childTier === "ignored")
+                    continue;
+            }
+            const timestampsPath = actualPath.replace(/\.md$/, ".timestamps.json");
             let timestamps;
             if (files.has(timestampsPath)) {
                 try {
                     timestamps = JSON.parse(files.get(timestampsPath));
                 }
                 catch {
-                    // JSON parse error - will fall back to inline timestamps
+                    /* fall back */
                 }
             }
-            for (const segment of section.segments) {
-                if (segment.type === 'video-excerpt') {
-                    const result = extractVideoExcerpt(sourceContent, segment.fromTimeStr, segment.toTimeStr, actualPath, timestamps);
-                    if (result.error) {
-                        errors.push({ ...result.error, file: lensPath });
-                    }
-                }
+            const sourceContent = files.get(actualPath);
+            const result = extractVideoExcerpt(sourceContent, segment.fromTimeStr, segment.toTimeStr, actualPath, timestamps);
+            if (result.error) {
+                errors.push({ ...result.error, file: lensPath });
             }
         }
     }
@@ -105,51 +175,58 @@ export function processContent(files) {
     const slugToPath = new Map();
     const filePathToSlug = new Map(); // Reverse: file path → slug (survives duplicate slugs)
     const courseSlugToFile = new Map();
+    const parentSlugToChildren = new Map();
     // Pre-scan: build tier map from frontmatter tags
     const tierMap = buildTierMap(files);
     // Identify file types by path
     for (const [path, content] of files.entries()) {
         // Skip ignored files entirely
-        if (tierMap.get(path) === 'ignored') {
+        if (tierMap.get(path) === "ignored") {
             continue;
         }
-        if (path.startsWith('modules/')) {
+        if (path.startsWith("modules/")) {
             const result = flattenModule(path, files, new Set(), tierMap);
-            if (result.module) {
-                modules.push(result.module);
-                slugToPath.set(result.module.slug, path);
-                filePathToSlug.set(path, result.module.slug);
-                // Collect slug for duplicate detection
-                slugEntries.push({
-                    slug: result.module.slug,
-                    file: path,
-                });
-                // Collect module contentId for UUID validation
-                if (result.module.contentId) {
+            for (const mod of result.modules) {
+                modules.push(mod);
+                slugToPath.set(mod.slug, path);
+                // Track parent→children mapping for course expansion
+                if (mod.parentSlug) {
+                    if (!parentSlugToChildren.has(mod.parentSlug)) {
+                        parentSlugToChildren.set(mod.parentSlug, []);
+                    }
+                    parentSlugToChildren.get(mod.parentSlug).push(mod.slug);
+                }
+                else {
+                    filePathToSlug.set(path, mod.slug);
+                }
+                slugEntries.push({ slug: mod.slug, file: path });
+                if (mod.contentId) {
                     uuidEntries.push({
-                        uuid: result.module.contentId,
+                        uuid: mod.contentId,
                         file: path,
-                        field: 'contentId',
+                        field: "contentId",
                     });
                 }
-                // Collect section-level id:: fields from raw # Page: sections.
-                // (Lens-derived sections inherit lens.id which is validated separately.)
+            }
+            // If no submodules, set filePathToSlug for the primary module
+            if (result.modules.length === 1 && !result.modules[0].parentSlug) {
+                filePathToSlug.set(path, result.modules[0].slug);
+            }
+            else if (result.modules.length > 0 && result.modules[0].parentSlug) {
+                // For split modules, map the file path to the parent slug
+                filePathToSlug.set(path, result.modules[0].parentSlug);
+            }
+            // Collect section-level id:: fields from Lens sections (inline lenses).
+            // Referenced lenses (with source::) get their id from the lens file itself.
+            if (result.modules.length > 0) {
                 const rawParse = parseModule(content, path);
                 if (rawParse.module) {
-                    for (const section of rawParse.module.sections) {
-                        if (section.type === 'page' && section.fields.id) {
-                            uuidEntries.push({
-                                uuid: section.fields.id,
-                                file: path,
-                                field: 'section id',
-                            });
-                        }
-                    }
+                    collectInlineLensUUIDs(rawParse.module.sections, path, uuidEntries, errors);
                 }
             }
             errors.push(...result.errors);
         }
-        else if (path.startsWith('courses/')) {
+        else if (path.startsWith("courses/")) {
             const result = parseCourse(content, path);
             if (result.course) {
                 courses.push(result.course);
@@ -157,35 +234,38 @@ export function processContent(files) {
             }
             errors.push(...result.errors);
         }
-        else if (path.startsWith('Learning Outcomes/') || path.includes('/Learning Outcomes/')) {
+        else if (path.startsWith("Learning Outcomes/") ||
+            path.includes("/Learning Outcomes/")) {
             // Fully validate Learning Outcome (structure, fields, wikilink syntax)
             const result = parseLearningOutcome(content, path);
             errors.push(...result.errors);
             // Check that referenced lens files exist
             if (result.learningOutcome) {
+                collectLearningOutcomeTestUUIDs(result.learningOutcome, path, uuidEntries);
                 for (const lensRef of result.learningOutcome.lenses) {
                     const lensPath = findFileWithExtension(lensRef.resolvedPath, files);
                     if (!lensPath) {
                         // Find similar files to suggest
-                        const similarFiles = findSimilarFiles(lensRef.resolvedPath, files, 'Lenses');
-                        const suggestion = formatSuggestion(similarFiles, path) ?? 'Check the file path in the wiki-link';
+                        const similarFiles = findSimilarFiles(lensRef.resolvedPath, files, "Lenses");
+                        const suggestion = formatSuggestion(similarFiles, path) ??
+                            "Check the file path in the wiki-link";
                         errors.push({
                             file: path,
                             message: `Referenced lens file not found: ${lensRef.resolvedPath}`,
                             suggestion,
-                            severity: 'error',
+                            severity: "error",
                         });
                         continue;
                     }
                     // Check tier violation (LO → Lens)
-                    const parentTier = tierMap.get(path) ?? 'production';
-                    const childTier = tierMap.get(lensPath) ?? 'production';
-                    const violation = checkTierViolation(path, parentTier, lensPath, childTier, 'lens');
+                    const parentTier = tierMap.get(path) ?? "production";
+                    const childTier = tierMap.get(lensPath) ?? "production";
+                    const violation = checkTierViolation(path, parentTier, lensPath, childTier, "lens");
                     if (violation) {
                         errors.push(violation);
                         continue;
                     }
-                    if (childTier === 'ignored') {
+                    if (childTier === "ignored") {
                         continue;
                     }
                 }
@@ -195,25 +275,20 @@ export function processContent(files) {
                 uuidEntries.push({
                     uuid: result.learningOutcome.id,
                     file: path,
-                    field: 'id',
+                    field: "id",
                 });
             }
         }
-        else if (path.startsWith('Lenses/') || path.includes('/Lenses/')) {
+        else if (path.startsWith("Lenses/") || path.includes("/Lenses/")) {
             // Fully validate Lens (structure, segments, fields)
             const result = parseLens(content, path);
             errors.push(...result.errors);
-            // Validate excerpts (source files exist, anchors/timestamps valid)
-            if (result.lens) {
-                const excerptErrors = validateLensExcerpts(result.lens, path, files, tierMap);
-                errors.push(...excerptErrors);
-            }
             // Collect id for UUID validation
             if (result.lens?.id) {
                 uuidEntries.push({
                     uuid: result.lens.id,
                     file: path,
-                    field: 'id',
+                    field: "id",
                 });
             }
             // Flatten lens as standalone module (pass pre-parsed lens to avoid re-parsing)
@@ -227,32 +302,65 @@ export function processContent(files) {
                 errors.push(...lensModuleResult.errors);
             }
         }
-        else if (path.endsWith('.timestamps.json')) {
+        else if (path.endsWith(".timestamps.json")) {
             const tsErrors = validateTimestamps(content, path);
             errors.push(...tsErrors);
         }
-        else if (path.startsWith('articles/') || path.includes('/articles/')) {
+        else if (path.startsWith("articles/") || path.includes("/articles/")) {
             const result = parseArticle(content, path);
             errors.push(...result.errors);
             if (result.article) {
-                urlsToValidate.push({ url: result.article.sourceUrl, file: path, line: 2, label: 'source_url' });
+                // Only carry the flag when set true, so URL entries (and thus the
+                // serialized output / Python parity) are unchanged for normal articles.
+                const overrideFlag = result.article.allowUnreachableUrl
+                    ? { allowUnreachable: true }
+                    : {};
+                urlsToValidate.push({
+                    url: result.article.sourceUrl,
+                    file: path,
+                    line: 2,
+                    label: "source_url",
+                    ...overrideFlag,
+                });
                 for (const img of result.article.imageUrls) {
-                    urlsToValidate.push({ url: img.url, file: path, line: img.line, label: 'Image URL' });
+                    urlsToValidate.push({
+                        url: img.url,
+                        file: path,
+                        line: img.line,
+                        label: "Image URL",
+                        ...overrideFlag,
+                    });
                 }
             }
         }
-        else if (path.startsWith('video_transcripts/') || path.includes('/video_transcripts/')) {
+        else if (path.startsWith("video_transcripts/") ||
+            path.includes("/video_transcripts/")) {
             const result = parseVideoTranscript(content, path);
             errors.push(...result.errors);
             if (result.transcript) {
-                urlsToValidate.push({ url: result.transcript.url, file: path, line: 2, label: 'url' });
+                urlsToValidate.push({
+                    url: result.transcript.url,
+                    file: path,
+                    line: 2,
+                    label: "url",
+                    ...(result.transcript.allowUnreachableUrl
+                        ? { allowUnreachable: true }
+                        : {}),
+                });
             }
         }
         else {
             // File didn't match any known directory pattern — check for near-misses via Levenshtein distance
-            const dir = path.split('/')[0];
-            const VALID_DIRS = ['modules', 'courses', 'articles', 'Lenses', 'video_transcripts', 'Learning Outcomes'];
-            let closest = '';
+            const dir = path.split("/")[0];
+            const VALID_DIRS = [
+                "modules",
+                "courses",
+                "articles",
+                "Lenses",
+                "video_transcripts",
+                "Learning Outcomes",
+            ];
+            let closest = "";
             let minDist = Infinity;
             for (const valid of VALID_DIRS) {
                 const dist = levenshtein(dir.toLowerCase(), valid.toLowerCase());
@@ -268,18 +376,38 @@ export function processContent(files) {
                     file: path,
                     message: `File in directory '${dir}/' not recognized as content`,
                     suggestion: `Did you mean '${closest}/'?`,
-                    severity: 'warning',
+                    severity: "warning",
                 });
             }
         }
     }
+    // Build contentId → moduleSlug mapping and populate moduleSlug in cross-module card links.
+    // Prefer real modules over standalone lenses (lens/ prefix) — a lens that appears in
+    // both a module and as a standalone should map to the module.
+    const contentIdToModuleSlug = new Map();
+    for (const mod of modules) {
+        if (mod.slug.startsWith("lens/"))
+            continue; // Skip standalone lenses
+        for (const section of mod.sections) {
+            if (section.contentId) {
+                contentIdToModuleSlug.set(section.contentId, mod.slug);
+            }
+        }
+    }
+    for (const mod of modules) {
+        populateCardModuleSlugs(mod.sections, contentIdToModuleSlug);
+        resolveInlineLensModuleSlugs(mod.sections, contentIdToModuleSlug);
+    }
+    // Card-to-module membership check. Runs after card link resolution above so
+    // every card has its data-lens-card JSON populated, including allowExternal.
+    errors.push(...validateCardModuleMembership(modules));
     // Resolve course module paths to frontmatter slugs.
     // Use filePathToSlug (built during module parsing) instead of inverting slugToPath,
     // because slugToPath loses entries when duplicate slugs exist.
     for (const course of courses) {
-        const courseFile = courseSlugToFile.get(course.slug) ?? 'courses/';
+        const courseFile = courseSlugToFile.get(course.slug) ?? "courses/";
         for (const item of course.progression) {
-            if (item.type === 'module' && item.path) {
+            if (item.type === "module" && item.path) {
                 // Resolve wikilink path relative to the course file
                 const resolved = resolveWikilinkPath(item.path, courseFile);
                 const actualFile = findFileWithExtension(resolved, files);
@@ -288,10 +416,10 @@ export function processContent(files) {
                 }
                 else {
                     // Try matching just the filename stem against module file stems
-                    const stem = item.path.split('/').pop() ?? item.path;
+                    const stem = item.path.split("/").pop() ?? item.path;
                     let matched = false;
                     for (const [filePath, slug] of filePathToSlug.entries()) {
-                        const fileStem = filePath.replace(/\.md$/, '').split('/').pop() ?? '';
+                        const fileStem = filePath.replace(/\.md$/, "").split("/").pop() ?? "";
                         if (fileStem === stem) {
                             item.slug = slug;
                             matched = true;
@@ -302,8 +430,8 @@ export function processContent(files) {
                         errors.push({
                             file: courseFile,
                             message: `Module reference could not be resolved: "${item.path}"`,
-                            suggestion: 'Check that the wikilink path points to an existing module file',
-                            severity: 'error',
+                            suggestion: "Check that the wikilink path points to an existing module file",
+                            severity: "error",
                         });
                     }
                 }
@@ -312,7 +440,23 @@ export function processContent(files) {
             }
         }
         // Remove unresolved module items (no slug after resolution)
-        course.progression = course.progression.filter(item => item.type !== 'module' || item.slug !== undefined);
+        course.progression = course.progression.filter((item) => item.type !== "module" || item.slug !== undefined);
+        // Expand split modules: replace parent slug with child submodule slugs
+        const expanded = [];
+        for (const item of course.progression) {
+            if (item.type === "module" &&
+                item.slug &&
+                parentSlugToChildren.has(item.slug)) {
+                const children = parentSlugToChildren.get(item.slug);
+                for (const childSlug of children) {
+                    expanded.push({ ...item, slug: childSlug });
+                }
+            }
+            else {
+                expanded.push(item);
+            }
+        }
+        course.progression = expanded;
     }
     // Check tier violations: Course → Module
     for (const course of courses) {
@@ -320,21 +464,48 @@ export function processContent(files) {
         if (!coursePath)
             continue;
         for (const item of course.progression) {
-            if (item.type !== 'module' || !item.slug)
+            if (item.type !== "module" || !item.slug)
                 continue;
-            // Construct expected module path and find it in files
-            const expectedModulePath = `modules/${item.slug}.md`;
-            const modulePath = findFileWithExtension(expectedModulePath, files) ?? expectedModulePath;
-            if (tierMap.has(modulePath)) {
-                const parentTier = tierMap.get(coursePath) ?? 'production';
-                const childTier = tierMap.get(modulePath) ?? 'production';
-                const violation = checkTierViolation(coursePath, parentTier, modulePath, childTier, 'module');
+            const modulePath = slugToPath.get(item.slug);
+            if (modulePath && tierMap.has(modulePath)) {
+                const parentTier = tierMap.get(coursePath) ?? "production";
+                const childTier = tierMap.get(modulePath) ?? "production";
+                const violation = checkTierViolation(coursePath, parentTier, modulePath, childTier, "module");
                 if (violation) {
                     errors.push(violation);
                 }
             }
         }
     }
+    // Validate course slug alias collisions
+    {
+        // Map of all course slugs (primary + aliases) -> source file
+        const allCourseSlugs = new Map(); // slug -> file
+        // Register primary slugs first
+        for (const course of courses) {
+            const file = courseSlugToFile.get(course.slug) ?? "courses/";
+            allCourseSlugs.set(course.slug, file);
+        }
+        // Check each alias against all known slugs
+        for (const course of courses) {
+            const file = courseSlugToFile.get(course.slug) ?? "courses/";
+            const tier = tierMap.get(file) ?? "production";
+            for (const alias of course.slugAliases ?? []) {
+                const existing = allCourseSlugs.get(alias);
+                if (existing) {
+                    errors.push({
+                        file,
+                        message: `Course slug alias '${alias}' collides with ${existing === file ? "its own primary slug" : `slug in ${existing}`}`,
+                        suggestion: `Choose a different alias or remove the conflicting slug`,
+                        severity: tier === "wip" ? "warning" : "error",
+                    });
+                }
+                else {
+                    allCourseSlugs.set(alias, file);
+                }
+            }
+        }
+    }
     // Validate all collected UUIDs
     const uuidValidation = validateUuids(uuidEntries);
     errors.push(...uuidValidation.errors);
@@ -342,29 +513,30 @@ export function processContent(files) {
     const duplicateSlugErrors = detectDuplicateSlugs(slugEntries);
     errors.push(...duplicateSlugErrors);
     // Validate video transcript / timestamps.json pairing
-    const transcriptPaths = [...files.keys()].filter(p => (p.startsWith('video_transcripts/') || p.includes('/video_transcripts/')) &&
-        p.endsWith('.md') &&
-        tierMap.get(p) !== 'ignored');
-    const timestampPaths = new Set([...files.keys()].filter(p => p.endsWith('.timestamps.json')));
+    const transcriptPaths = [...files.keys()].filter((p) => (p.startsWith("video_transcripts/") ||
+        p.includes("/video_transcripts/")) &&
+        p.endsWith(".md") &&
+        tierMap.get(p) !== "ignored");
+    const timestampPaths = new Set([...files.keys()].filter((p) => p.endsWith(".timestamps.json")));
     for (const mdPath of transcriptPaths) {
-        const expectedTs = mdPath.replace(/\.md$/, '.timestamps.json');
+        const expectedTs = mdPath.replace(/\.md$/, ".timestamps.json");
         if (!timestampPaths.has(expectedTs)) {
             errors.push({
                 file: mdPath,
                 message: `Missing timestamps.json: expected ${expectedTs}`,
-                severity: 'error',
+                severity: "error",
             });
         }
     }
     for (const tsPath of timestampPaths) {
-        const expectedMd = tsPath.replace(/\.timestamps\.json$/, '.md');
-        if (tierMap.get(expectedMd) === 'ignored')
+        const expectedMd = tsPath.replace(/\.timestamps\.json$/, ".md");
+        if (tierMap.get(expectedMd) === "ignored")
             continue;
         if (!files.has(expectedMd)) {
             errors.push({
                 file: tsPath,
                 message: `Orphaned timestamps file: no matching .md transcript found`,
-                severity: 'warning',
+                severity: "warning",
             });
         }
     }
@@ -375,9 +547,12 @@ export function processContent(files) {
     for (const error of errors) {
         if (!error.category) {
             const tier = tierMap.get(error.file);
-            error.category = tier === 'wip' ? 'wip' : 'production';
+            error.category = tier === "wip" ? "wip" : "production";
         }
     }
-    return { modules, courses, errors, urlsToValidate };
+    // The same file is validated once per pass (standalone + once per module
+    // that flattens it), so identical errors are emitted multiple times. Collapse
+    // them so each problem is reported once.
+    return { modules, courses, errors: dedupeErrors(errors), urlsToValidate };
 }
 //# sourceMappingURL=index.js.map