stego-cli 0.4.1 → 0.4.2

package/dist/stego-cli/src/modules/quality/application/inspect-project.js

@@ -0,0 +1,603 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseCommentAppendix } from "../../../../../shared/src/domain/comments/index.js";
+import { isStageName } from "../../../../../shared/src/domain/stages/index.js";
+import { readSpineCatalogForProject } from "../../spine/index.js";
+export function inspectProject(project, options = {}) {
+    const repoRoot = project.workspace.repoRoot;
+    const runtimeConfig = project.workspace.config;
+    const issues = [];
+    const emptySpineState = { categories: [], entriesByCategory: new Map(), issues: [] };
+    const requiredMetadataState = resolveRequiredMetadata(project);
+    const compileStructureState = resolveCompileStructure(project);
+    issues.push(...requiredMetadataState.issues);
+    issues.push(...compileStructureState.issues);
+    if (project.meta.spineCategories !== undefined) {
+        issues.push(makeIssue("error", "metadata", "Legacy 'spineCategories' in stego-project.json is no longer supported. Use spine/ category directories and files.", path.relative(repoRoot, path.join(project.root, "stego-project.json"))));
+    }
+    const spineState = readSpine(project);
+    issues.push(...spineState.issues);
+    let chapterFiles = [];
+    const onlyFile = options.onlyFile?.trim();
+    if (onlyFile) {
+        const resolvedPath = path.resolve(project.root, onlyFile);
+        const relativeToProject = path.relative(project.root, resolvedPath);
+        if (!relativeToProject || relativeToProject.startsWith("..") || path.isAbsolute(relativeToProject)) {
+            issues.push(makeIssue("error", "structure", `Requested file is outside the project: ${onlyFile}`, null));
+            return { chapters: [], issues, spineState: emptySpineState, compileStructureLevels: compileStructureState.levels };
+        }
+        if (!fs.existsSync(resolvedPath)) {
+            issues.push(makeIssue("error", "structure", `Requested file does not exist: ${onlyFile}`, null));
+            return { chapters: [], issues, spineState: emptySpineState, compileStructureLevels: compileStructureState.levels };
+        }
+        if (!fs.statSync(resolvedPath).isFile() || !resolvedPath.endsWith(".md")) {
+            issues.push(makeIssue("error", "structure", `Requested file must be a markdown file: ${onlyFile}`, null));
+            return { chapters: [], issues, spineState: emptySpineState, compileStructureLevels: compileStructureState.levels };
+        }
+        const relativeToManuscript = path.relative(project.manuscriptDir, resolvedPath);
+        if (relativeToManuscript.startsWith("..") || path.isAbsolute(relativeToManuscript)) {
+            issues.push(makeIssue("error", "structure", `Requested file must be inside manuscript directory: ${project.manuscriptDir}`, null));
+            return { chapters: [], issues, spineState: emptySpineState, compileStructureLevels: compileStructureState.levels };
+        }
+        chapterFiles = [resolvedPath];
+    }
+    else {
+        if (!fs.existsSync(project.manuscriptDir)) {
+            issues.push(makeIssue("error", "structure", `Missing manuscript directory: ${project.manuscriptDir}`));
+            return { chapters: [], issues, spineState: emptySpineState, compileStructureLevels: compileStructureState.levels };
+        }
+        chapterFiles = fs
+            .readdirSync(project.manuscriptDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+            .map((entry) => path.join(project.manuscriptDir, entry.name))
+            .sort();
+        if (chapterFiles.length === 0) {
+            issues.push(makeIssue("error", "structure", `No manuscript files found in ${project.manuscriptDir}`));
+            return { chapters: [], issues, spineState: emptySpineState, compileStructureLevels: compileStructureState.levels };
+        }
+    }
+    const chapters = chapterFiles.map((chapterPath) => parseChapter(chapterPath, project, requiredMetadataState.requiredMetadata, spineState.categories, compileStructureState.levels));
+    for (const chapter of chapters) {
+        issues.push(...chapter.issues);
+    }
+    const orderMap = new Map();
+    for (const chapter of chapters) {
+        if (chapter.order == null) {
+            continue;
+        }
+        if (orderMap.has(chapter.order)) {
+            issues.push(makeIssue("error", "ordering", `Duplicate filename order prefix '${chapter.order}' in ${chapter.relativePath} and ${orderMap.get(chapter.order)}`, chapter.relativePath));
+            continue;
+        }
+        orderMap.set(chapter.order, chapter.relativePath);
+    }
+    chapters.sort((a, b) => {
+        if (a.order == null && b.order == null) {
+            return a.relativePath.localeCompare(b.relativePath);
+        }
+        if (a.order == null) {
+            return 1;
+        }
+        if (b.order == null) {
+            return -1;
+        }
+        return a.order - b.order;
+    });
+    for (const chapter of chapters) {
+        issues.push(...findUnknownSpineReferences(chapter.referenceKeysByCategory, spineState.entriesByCategory, chapter.relativePath));
+    }
+    return {
+        chapters,
+        issues,
+        spineState,
+        compileStructureLevels: compileStructureState.levels
+    };
+}
+export function resolveRequiredMetadata(project) {
+    const repoRoot = project.workspace.repoRoot;
+    const runtimeConfig = project.workspace.config;
+    const issues = [];
+    const projectFile = path.relative(repoRoot, path.join(project.root, "stego-project.json"));
+    const raw = project.meta.requiredMetadata;
+    if (raw == null) {
+        return { requiredMetadata: runtimeConfig.requiredMetadata, issues };
+    }
+    if (!Array.isArray(raw)) {
+        issues.push(makeIssue("error", "metadata", "Project 'requiredMetadata' must be an array of metadata keys.", projectFile));
+        return { requiredMetadata: runtimeConfig.requiredMetadata, issues };
+    }
+    const requiredMetadata = [];
+    const seen = new Set();
+    for (const [index, entry] of raw.entries()) {
+        if (typeof entry !== "string") {
+            issues.push(makeIssue("error", "metadata", `Project 'requiredMetadata' entry at index ${index} must be a string.`, projectFile));
+            continue;
+        }
+        const key = entry.trim();
+        if (!key) {
+            issues.push(makeIssue("error", "metadata", `Project 'requiredMetadata' entry at index ${index} cannot be empty.`, projectFile));
+            continue;
+        }
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        requiredMetadata.push(key);
+    }
+    return { requiredMetadata, issues };
+}
+export function resolveCompileStructure(project) {
+    const repoRoot = project.workspace.repoRoot;
+    const issues = [];
+    const projectFile = path.relative(repoRoot, path.join(project.root, "stego-project.json"));
+    const raw = project.meta.compileStructure;
+    if (raw == null) {
+        return { levels: [], issues };
+    }
+    if (!isPlainObject(raw)) {
+        issues.push(makeIssue("error", "metadata", "Project 'compileStructure' must be an object.", projectFile));
+        return { levels: [], issues };
+    }
+    const rawLevels = raw.levels;
+    if (!Array.isArray(rawLevels)) {
+        issues.push(makeIssue("error", "metadata", "Project 'compileStructure.levels' must be an array.", projectFile));
+        return { levels: [], issues };
+    }
+    const levels = [];
+    const seenKeys = new Set();
+    for (const [index, entry] of rawLevels.entries()) {
+        if (!isPlainObject(entry)) {
+            issues.push(makeIssue("error", "metadata", `Invalid compileStructure level at index ${index}. Expected object.`, projectFile));
+            continue;
+        }
+        const key = typeof entry.key === "string" ? entry.key.trim() : "";
+        const label = typeof entry.label === "string" ? entry.label.trim() : "";
+        const titleKeyRaw = typeof entry.titleKey === "string" ? entry.titleKey.trim() : "";
+        const headingTemplateRaw = typeof entry.headingTemplate === "string" ? entry.headingTemplate.trim() : "";
+        if (!key || !/^[a-z][a-z0-9_-]*$/.test(key)) {
+            issues.push(makeIssue("error", "metadata", `compileStructure.levels[${index}].key must match /^[a-z][a-z0-9_-]*$/.`, projectFile));
+            continue;
+        }
+        if (!label) {
+            issues.push(makeIssue("error", "metadata", `compileStructure.levels[${index}].label is required.`, projectFile));
+            continue;
+        }
+        if (seenKeys.has(key)) {
+            issues.push(makeIssue("error", "metadata", `Duplicate compileStructure level key '${key}'.`, projectFile));
+            continue;
+        }
+        if (titleKeyRaw && !/^[a-z][a-z0-9_-]*$/.test(titleKeyRaw)) {
+            issues.push(makeIssue("error", "metadata", `compileStructure.levels[${index}].titleKey must match /^[a-z][a-z0-9_-]*$/.`, projectFile));
+            continue;
+        }
+        const pageBreakRaw = typeof entry.pageBreak === "string" ? entry.pageBreak.trim() : "between-groups";
+        if (pageBreakRaw !== "none" && pageBreakRaw !== "between-groups") {
+            issues.push(makeIssue("error", "metadata", `compileStructure.levels[${index}].pageBreak must be 'none' or 'between-groups'.`, projectFile));
+            continue;
+        }
+        const injectHeading = typeof entry.injectHeading === "boolean" ? entry.injectHeading : true;
+        const headingTemplate = headingTemplateRaw || "{label} {value}: {title}";
+        seenKeys.add(key);
+        levels.push({
+            key,
+            label,
+            titleKey: titleKeyRaw || undefined,
+            injectHeading,
+            headingTemplate,
+            pageBreak: pageBreakRaw
+        });
+    }
+    return { levels, issues };
+}
+export function issueHasErrors(issues) {
+    return issues.some((issue) => issue.level === "error");
+}
+export function formatIssues(issues) {
+    return issues.map((issue) => {
+        const filePart = issue.file ? ` ${issue.file}` : "";
+        const linePart = issue.line ? `:${issue.line}` : "";
+        return `[${issue.level.toUpperCase()}][${issue.category}]${filePart}${linePart} ${issue.message}`;
+    });
+}
+function parseChapter(chapterPath, project, requiredMetadata, spineCategories, compileStructureLevels) {
+    const repoRoot = project.workspace.repoRoot;
+    const runtimeConfig = project.workspace.config;
+    const relativePath = path.relative(repoRoot, chapterPath);
+    const raw = fs.readFileSync(chapterPath, "utf8");
+    const { metadata, body, comments, issues } = parseMetadata(raw, chapterPath, repoRoot, false);
+    const chapterIssues = [...issues];
+    for (const requiredKey of requiredMetadata) {
+        if (metadata[requiredKey] == null || metadata[requiredKey] === "") {
+            chapterIssues.push(makeIssue("warning", "metadata", `Missing required metadata key '${requiredKey}'. Validation and stage checks that depend on '${requiredKey}' are skipped for this file.`, relativePath));
+        }
+    }
+    const title = deriveEntryTitle(metadata.title, chapterPath);
+    if (metadata.order != null && metadata.order !== "") {
+        chapterIssues.push(makeIssue("warning", "metadata", "Metadata 'order' is ignored. Ordering is derived from filename prefix.", relativePath));
+    }
+    const order = parseOrderFromFilename(chapterPath, relativePath, chapterIssues);
+    const status = String(metadata.status || "").trim();
+    if (status && !isStageName(status)) {
+        chapterIssues.push(makeIssue("error", "metadata", `Invalid file status '${status}'. Allowed: ${runtimeConfig.allowedStatuses.join(", ")}.`, relativePath));
+    }
+    const groupValues = {};
+    for (const level of compileStructureLevels) {
+        const groupValue = normalizeGroupingValue(metadata[level.key], relativePath, chapterIssues, level.key);
+        if (groupValue) {
+            groupValues[level.key] = groupValue;
+        }
+        if (level.titleKey) {
+            void normalizeGroupingValue(metadata[level.titleKey], relativePath, chapterIssues, level.titleKey);
+        }
+    }
+    const referenceValidation = extractReferenceKeysByCategory(metadata, relativePath, spineCategories);
+    chapterIssues.push(...referenceValidation.issues);
+    chapterIssues.push(...validateMarkdownBody(body, chapterPath, repoRoot));
+    return {
+        path: chapterPath,
+        relativePath,
+        title,
+        order,
+        status,
+        referenceKeysByCategory: referenceValidation.referencesByCategory,
+        groupValues,
+        metadata,
+        body,
+        comments,
+        issues: chapterIssues
+    };
+}
+function normalizeGroupingValue(rawValue, relativePath, issues, key) {
+    if (rawValue == null || rawValue === "") {
+        return undefined;
+    }
+    if (Array.isArray(rawValue)) {
+        issues.push(makeIssue("error", "metadata", `Metadata '${key}' must be a scalar value.`, relativePath));
+        return undefined;
+    }
+    const normalized = String(rawValue).trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function deriveEntryTitle(rawTitle, chapterPath) {
+    if (typeof rawTitle === "string" && rawTitle.trim()) {
+        return rawTitle.trim();
+    }
+    const basename = path.basename(chapterPath, ".md");
+    const withoutPrefix = basename.replace(/^\d+[-_]?/, "");
+    const normalized = withoutPrefix.replace(/[-_]+/g, " ").trim();
+    if (!normalized) {
+        return basename;
+    }
+    return normalized.replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function parseOrderFromFilename(chapterPath, relativePath, issues) {
+    const basename = path.basename(chapterPath, ".md");
+    const match = basename.match(/^(\d+)[-_]/);
+    if (!match) {
+        issues.push(makeIssue("error", "ordering", "Filename must start with a numeric prefix followed by '-' or '_' (for example '100-scene.md').", relativePath));
+        return null;
+    }
+    if (match[1].length !== 3) {
+        issues.push(makeIssue("warning", "ordering", `Filename prefix '${match[1]}' is valid but non-standard. Use three digits like 100, 200, 300.`, relativePath));
+    }
+    return Number(match[1]);
+}
+function extractReferenceKeysByCategory(metadata, relativePath, spineCategories) {
+    const issues = [];
+    const referencesByCategory = {};
+    for (const category of spineCategories) {
+        const rawValue = metadata[category.key];
+        if (rawValue == null || rawValue === "") {
+            continue;
+        }
+        if (!Array.isArray(rawValue)) {
+            issues.push(makeIssue("error", "metadata", `Metadata '${category.key}' must be an array of spine entry keys (for example: [\"matthaeus\"]).`, relativePath));
+            continue;
+        }
+        const seen = new Set();
+        const values = [];
+        for (const entry of rawValue) {
+            if (typeof entry !== "string") {
+                issues.push(makeIssue("error", "metadata", `Metadata '${category.key}' entries must be strings.`, relativePath));
+                continue;
+            }
+            const normalized = entry.trim();
+            if (!normalized) {
+                issues.push(makeIssue("error", "metadata", `Metadata '${category.key}' contains an empty entry key.`, relativePath));
+                continue;
+            }
+            if (seen.has(normalized)) {
+                continue;
+            }
+            seen.add(normalized);
+            values.push(normalized);
+        }
+        referencesByCategory[category.key] = values;
+    }
+    return { referencesByCategory, issues };
+}
+function parseMetadata(raw, chapterPath, repoRoot, required) {
+    const relativePath = path.relative(repoRoot, chapterPath);
+    const issues = [];
+    if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) {
+        const commentsResult = parseStegoCommentsAppendix(raw, relativePath, 1);
+        if (!required) {
+            return {
+                metadata: {},
+                body: commentsResult.bodyWithoutComments,
+                comments: commentsResult.comments,
+                issues: commentsResult.issues
+            };
+        }
+        return {
+            metadata: {},
+            body: commentsResult.bodyWithoutComments,
+            comments: commentsResult.comments,
+            issues: [makeIssue("error", "metadata", "Missing metadata block at top of file.", relativePath), ...commentsResult.issues]
+        };
+    }
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match) {
+        return {
+            metadata: {},
+            body: raw,
+            comments: [],
+            issues: [makeIssue("error", "metadata", "Metadata opening delimiter found, but closing delimiter is missing.", relativePath)]
+        };
+    }
+    const metadataText = match[1];
+    const body = raw.slice(match[0].length);
+    const metadata = {};
+    const lines = metadataText.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex === -1) {
+            issues.push(makeIssue("error", "metadata", `Invalid metadata line '${line}'. Expected 'key: value' format.`, relativePath, i + 1));
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        if (!value) {
+            let lookahead = i + 1;
+            while (lookahead < lines.length) {
+                const nextTrimmed = lines[lookahead].trim();
+                if (!nextTrimmed || nextTrimmed.startsWith("#")) {
+                    lookahead += 1;
+                    continue;
+                }
+                break;
+            }
+            if (lookahead < lines.length) {
+                const firstValueLine = lines[lookahead];
+                const firstValueTrimmed = firstValueLine.trim();
+                const firstValueIndent = firstValueLine.length - firstValueLine.trimStart().length;
+                if (firstValueIndent > 0 && firstValueTrimmed.startsWith("- ")) {
+                    const items = [];
+                    let j = lookahead;
+                    while (j < lines.length) {
+                        const candidateRaw = lines[j];
+                        const candidateTrimmed = candidateRaw.trim();
+                        if (!candidateTrimmed || candidateTrimmed.startsWith("#")) {
+                            j += 1;
+                            continue;
+                        }
+                        const indent = candidateRaw.length - candidateRaw.trimStart().length;
+                        if (indent === 0) {
+                            break;
+                        }
+                        if (!candidateTrimmed.startsWith("- ")) {
+                            issues.push(makeIssue("error", "metadata", `Unsupported metadata list line '${candidateTrimmed}'. Expected '- value'.`, relativePath, j + 1));
+                            j += 1;
+                            continue;
+                        }
+                        const itemValue = candidateTrimmed.slice(2).trim().replace(/^['"]|['"]$/g, "");
+                        items.push(itemValue);
+                        j += 1;
+                    }
+                    metadata[key] = items;
+                    i = j - 1;
+                    continue;
+                }
+            }
+        }
+        metadata[key] = coerceMetadataValue(value);
+    }
+    const bodyStartLine = match[0].split(/\r?\n/).length;
+    const commentsResult = parseStegoCommentsAppendix(body, relativePath, bodyStartLine);
+    issues.push(...commentsResult.issues);
+    return {
+        metadata,
+        body: commentsResult.bodyWithoutComments,
+        comments: commentsResult.comments,
+        issues
+    };
+}
+function parseStegoCommentsAppendix(body, relativePath, bodyStartLine) {
+    const parsed = parseCommentAppendix(body);
+    const issues = parsed.errors.map((error) => parseCommentIssueFromParserError(error, relativePath, bodyStartLine));
+    const comments = parsed.comments.map((comment) => ({
+        id: comment.id,
+        resolved: comment.status === "resolved",
+        thread: comment.thread
+    }));
+    return {
+        bodyWithoutComments: parsed.contentWithoutComments,
+        comments,
+        issues
+    };
+}
+function parseCommentIssueFromParserError(error, relativePath, bodyStartLine) {
+    const lineMatch = error.match(/^Line\s+(\d+):\s+([\s\S]+)$/);
+    if (!lineMatch) {
+        return makeIssue("error", "comments", error, relativePath);
+    }
+    const relativeLine = Number.parseInt(lineMatch[1], 10);
+    const absoluteLine = Number.isFinite(relativeLine) ? bodyStartLine + relativeLine - 1 : undefined;
+    return makeIssue("error", "comments", lineMatch[2], relativePath, absoluteLine);
+}
+function coerceMetadataValue(value) {
+    if (!value) {
+        return "";
+    }
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    if (value.startsWith("[") && value.endsWith("]")) {
+        const inner = value.slice(1, -1).trim();
+        if (!inner) {
+            return [];
+        }
+        return inner.split(",").map((entry) => entry.trim().replace(/^['\"]|['\"]$/g, ""));
+    }
+    if (/^-?\d+$/.test(value)) {
+        return Number(value);
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    return value;
+}
+function validateMarkdownBody(body, chapterPath, repoRoot) {
+    const relativePath = path.relative(repoRoot, chapterPath);
+    const issues = [];
+    const lines = body.split(/\r?\n/);
+    let openFence = null;
+    let previousHeadingLevel = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const fenceMatch = line.match(/^(```+|~~~+)/);
+        if (fenceMatch) {
+            const marker = fenceMatch[1][0];
+            const length = fenceMatch[1].length;
+            if (!openFence) {
+                openFence = { marker, length, line: i + 1 };
+            }
+            else if (openFence.marker === marker && length >= openFence.length) {
+                openFence = null;
+            }
+            continue;
+        }
+        const headingMatch = line.match(/^(#{1,6})\s+/);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            if (previousHeadingLevel > 0 && level > previousHeadingLevel + 1) {
+                issues.push(makeIssue("warning", "style", `Heading level jumps from H${previousHeadingLevel} to H${level}.`, relativePath, i + 1));
+            }
+            previousHeadingLevel = level;
+        }
+        if (/\[[^\]]+\]\([^\)]*$/.test(line.trim())) {
+            issues.push(makeIssue("error", "structure", "Malformed markdown link, missing closing ')'.", relativePath, i + 1));
+        }
+    }
+    if (openFence) {
+        issues.push(makeIssue("error", "structure", `Unclosed code fence opened at line ${openFence.line}.`, relativePath, openFence.line));
+    }
+    issues.push(...checkLocalMarkdownLinks(body, chapterPath, repoRoot));
+    issues.push(...runStyleHeuristics(body, relativePath));
+    return issues;
+}
+function checkLocalMarkdownLinks(body, chapterPath, repoRoot) {
+    const relativePath = path.relative(repoRoot, chapterPath);
+    const issues = [];
+    const linkRegex = /!?\[[^\]]*\]\(([^)]+)\)/g;
+    let match = null;
+    while ((match = linkRegex.exec(body)) !== null) {
+        let target = match[1].trim();
+        if (!target) {
+            continue;
+        }
+        if (target.startsWith("<") && target.endsWith(">")) {
+            target = target.slice(1, -1).trim();
+        }
+        target = target.split(/\s+"/)[0].split(/\s+'/)[0].trim();
+        if (isExternalTarget(target) || target.startsWith("#")) {
+            continue;
+        }
+        const cleanTarget = target.split("#")[0];
+        if (!cleanTarget) {
+            continue;
+        }
+        const resolved = path.resolve(path.dirname(chapterPath), cleanTarget);
+        if (!fs.existsSync(resolved)) {
+            issues.push(makeIssue("warning", "links", `Broken local link/image target '${cleanTarget}'.`, relativePath));
+        }
+    }
+    return issues;
+}
+function isExternalTarget(target) {
+    return (target.startsWith("http://")
+        || target.startsWith("https://")
+        || target.startsWith("mailto:")
+        || target.startsWith("tel:"));
+}
+function runStyleHeuristics(body, relativePath) {
+    const issues = [];
+    const prose = body
+        .replace(/```[\s\S]*?```/g, "")
+        .replace(/~~~[\s\S]*?~~~/g, "");
+    const paragraphs = prose
+        .split(/\n\s*\n/)
+        .map((paragraph) => paragraph.trim())
+        .filter((paragraph) => paragraph.length > 0)
+        .filter((paragraph) => !paragraph.startsWith("#"))
+        .filter((paragraph) => !paragraph.startsWith("- "));
+    for (const paragraph of paragraphs) {
+        const words = countWords(paragraph);
+        if (words > 180) {
+            issues.push(makeIssue("warning", "style", `Long paragraph detected (${words} words).`, relativePath));
+        }
+        const sentences = paragraph.split(/[.!?]+\s+/).map((sentence) => sentence.trim()).filter(Boolean);
+        for (const sentence of sentences) {
+            const sentenceWords = countWords(sentence);
+            if (sentenceWords > 45) {
+                issues.push(makeIssue("warning", "style", `Long sentence detected (${sentenceWords} words).`, relativePath));
+            }
+        }
+    }
+    return issues;
+}
+function countWords(text) {
+    return text.trim().split(/\s+/).filter(Boolean).length;
+}
+function readSpine(project) {
+    const catalogEnvelope = readSpineCatalogForProject(project);
+    const categories = [];
+    const entriesByCategory = new Map();
+    for (const category of catalogEnvelope.state.categories) {
+        const entries = new Set(category.entries.map((entry) => entry.key));
+        categories.push({ key: category.key, entries });
+        entriesByCategory.set(category.key, entries);
+    }
+    const issues = catalogEnvelope.state.issues.map((message) => makeIssue("warning", "continuity", message));
+    return { categories, entriesByCategory, issues };
+}
+function findUnknownSpineReferences(referencesByCategory, entriesByCategory, relativePath) {
+    const issues = [];
+    for (const [categoryKey, values] of Object.entries(referencesByCategory)) {
+        const known = entriesByCategory.get(categoryKey);
+        if (!known) {
+            issues.push(makeIssue("warning", "continuity", `Metadata category '${categoryKey}' has references but no matching spine category directory was found in spine/.`, relativePath));
+            continue;
+        }
+        for (const value of values) {
+            if (known.has(value)) {
+                continue;
+            }
+            issues.push(makeIssue("warning", "continuity", `Metadata reference '${categoryKey}: ${value}' does not exist in spine/${categoryKey}/.`, relativePath));
+        }
+    }
+    return issues;
+}
+function makeIssue(level, category, message, file = null, line = null) {
+    return { level, category, message, file, line };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}