stego-cli 0.4.0 → 0.4.2

package/dist/stego-cli/src/modules/quality/application/lint-runner.js

@@ -0,0 +1,313 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseCommentAppendix } from "../../../../../shared/src/domain/comments/index.js";
+export function resolveLintSelection(options) {
+    const manuscript = readBooleanOption(options, "manuscript");
+    const spine = readBooleanOption(options, "spine");
+    if (!manuscript && !spine) {
+        return { manuscript: true, spine: true };
+    }
+    return { manuscript, spine };
+}
+export function formatLintSelection(selection) {
+    if (selection.manuscript && selection.spine) {
+        return "manuscript + spine";
+    }
+    if (selection.manuscript) {
+        return "manuscript";
+    }
+    if (selection.spine) {
+        return "spine";
+    }
+    return "none";
+}
+export function runProjectLint(project, selection) {
+    const issues = [];
+    let fileCount = 0;
+    if (selection.manuscript) {
+        const manuscriptFiles = collectTopLevelMarkdownFiles(project.manuscriptDir);
+        if (manuscriptFiles.length === 0) {
+            issues.push(makeIssue("error", "lint", `No manuscript markdown files found in ${project.manuscriptDir}`));
+        }
+        else {
+            fileCount += manuscriptFiles.length;
+            issues.push(...runMarkdownlint(project, manuscriptFiles, true, "manuscript"));
+        }
+    }
+    if (selection.spine) {
+        const spineLintState = collectSpineLintMarkdownFiles(project);
+        issues.push(...spineLintState.issues);
+        if (spineLintState.files.length > 0) {
+            fileCount += spineLintState.files.length;
+            issues.push(...runMarkdownlint(project, spineLintState.files, true, "default"));
+        }
+    }
+    if (fileCount === 0 && issues.length === 0) {
+        issues.push(makeIssue("error", "lint", `No markdown files found for lint scope '${formatLintSelection(selection)}' in project '${project.id}'.`));
+    }
+    return { issues, fileCount };
+}
+export function runMarkdownlint(project, files, required, profile = "default") {
+    if (files.length === 0) {
+        return [];
+    }
+    const markdownlintCommand = resolveCommand(project.workspace.repoRoot, "markdownlint");
+    if (!markdownlintCommand) {
+        if (required) {
+            return [
+                makeIssue("error", "tooling", "markdownlint is required for this command but not installed. Run 'npm i' in the repo root.")
+            ];
+        }
+        return [];
+    }
+    const repoRoot = project.workspace.repoRoot;
+    const manuscriptProjectConfigPath = path.join(project.root, ".markdownlint.manuscript.json");
+    const manuscriptRepoConfigPath = path.join(repoRoot, ".markdownlint.manuscript.json");
+    const defaultProjectConfigPath = path.join(project.root, ".markdownlint.json");
+    const defaultRepoConfigPath = path.join(repoRoot, ".markdownlint.json");
+    const markdownlintConfigPath = profile === "manuscript"
+        ? (fs.existsSync(manuscriptProjectConfigPath)
+            ? manuscriptProjectConfigPath
+            : fs.existsSync(manuscriptRepoConfigPath)
+                ? manuscriptRepoConfigPath
+                : fs.existsSync(defaultProjectConfigPath)
+                    ? defaultProjectConfigPath
+                    : defaultRepoConfigPath)
+        : (fs.existsSync(defaultProjectConfigPath)
+            ? defaultProjectConfigPath
+            : defaultRepoConfigPath);
+    const prepared = prepareFilesWithoutComments(project.workspace.repoRoot, files);
+    try {
+        const result = spawnSync(markdownlintCommand, ["--config", markdownlintConfigPath, ...prepared.files], {
+            cwd: repoRoot,
+            encoding: "utf8"
+        });
+        if (result.status === 0) {
+            return [];
+        }
+        const details = remapToolOutputPaths(compactToolOutput(result.stdout, result.stderr), prepared.pathMap, project.workspace.repoRoot);
+        return [makeIssue(required ? "error" : "warning", "lint", `markdownlint reported issues. ${details}`)];
+    }
+    finally {
+        prepared.cleanup();
+    }
+}
+export function runCSpell(project, files, required, extraWords = []) {
+    const cspellCommand = resolveCommand(project.workspace.repoRoot, "cspell");
+    if (!cspellCommand) {
+        if (required) {
+            return [
+                makeIssue("error", "tooling", "cspell is required for this stage but not installed. Run 'npm i' in the repo root.")
+            ];
+        }
+        return [];
+    }
+    const repoRoot = project.workspace.repoRoot;
+    let tempConfigDir = null;
+    let cspellConfigPath = path.join(repoRoot, ".cspell.json");
+    if (extraWords.length > 0) {
+        const baseConfig = readJson(cspellConfigPath);
+        const existingWords = Array.isArray(baseConfig.words)
+            ? baseConfig.words.filter((word) => typeof word === "string")
+            : [];
+        const mergedWords = new Set([...existingWords, ...extraWords]);
+        tempConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "stego-cspell-"));
+        cspellConfigPath = path.join(tempConfigDir, "cspell.generated.json");
+        fs.writeFileSync(cspellConfigPath, `${JSON.stringify({ ...baseConfig, words: Array.from(mergedWords).sort() }, null, 2)}\n`, "utf8");
+    }
+    const prepared = prepareFilesWithoutComments(repoRoot, files);
+    try {
+        const result = spawnSync(cspellCommand, ["--no-progress", "--no-summary", "--config", cspellConfigPath, ...prepared.files], {
+            cwd: repoRoot,
+            encoding: "utf8"
+        });
+        if (result.status === 0) {
+            return [];
+        }
+        const details = remapToolOutputPaths(compactToolOutput(result.stdout, result.stderr), prepared.pathMap, repoRoot);
+        return [
+            makeIssue(required ? "error" : "warning", "spell", `cspell reported issues. ${details} Words from spine identifiers are auto-whitelisted. For additional terms, add them to '.cspell.json' under the 'words' array.`)
+        ];
+    }
+    finally {
+        prepared.cleanup();
+        if (tempConfigDir) {
+            fs.rmSync(tempConfigDir, { recursive: true, force: true });
+        }
+    }
+}
+export function collectSpineWordsForSpellcheck(entriesByCategory) {
+    const words = new Set();
+    for (const [category, entries] of entriesByCategory) {
+        const categoryParts = category
+            .split(/[-_/]+/)
+            .map((part) => part.trim())
+            .filter(Boolean);
+        for (const part of categoryParts) {
+            if (/[A-Za-z]/.test(part)) {
+                words.add(part.toLowerCase());
+            }
+        }
+        for (const entry of entries) {
+            const entryParts = entry
+                .split(/[-_/]+/)
+                .map((part) => part.trim())
+                .filter(Boolean);
+            for (const part of entryParts) {
+                if (!/[A-Za-z]/.test(part)) {
+                    continue;
+                }
+                words.add(part.toLowerCase());
+            }
+        }
+    }
+    return Array.from(words).sort();
+}
+function collectSpineLintMarkdownFiles(project) {
+    const issues = [];
+    const files = new Set();
+    addMarkdownFilesFromDirectory(files, project.spineDir, true);
+    if (!fs.existsSync(project.spineDir)) {
+        issues.push(makeIssue("warning", "lint", `Missing spine directory: ${project.spineDir}`));
+    }
+    addMarkdownFilesFromDirectory(files, project.notesDir, true);
+    if (!fs.existsSync(project.notesDir)) {
+        issues.push(makeIssue("warning", "lint", `Missing notes directory: ${project.notesDir}`));
+    }
+    for (const file of collectTopLevelMarkdownFiles(project.root)) {
+        files.add(file);
+    }
+    const sortedFiles = Array.from(files).sort();
+    if (sortedFiles.length === 0) {
+        issues.push(makeIssue("error", "lint", `No spine/notes markdown files found in ${project.spineDir}, ${project.notesDir}, or project root.`));
+    }
+    return { files: sortedFiles, issues };
+}
+function collectTopLevelMarkdownFiles(directory) {
+    if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
+        return [];
+    }
+    return fs
+        .readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => path.join(directory, entry.name))
+        .sort();
+}
+function addMarkdownFilesFromDirectory(target, directory, recursive) {
+    if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
+        return;
+    }
+    const stack = [directory];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current) {
+            continue;
+        }
+        const entries = fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isFile() && entry.name.endsWith(".md")) {
+                target.add(fullPath);
+                continue;
+            }
+            if (recursive && entry.isDirectory()) {
+                stack.push(fullPath);
+            }
+        }
+    }
+}
+function prepareFilesWithoutComments(repoRoot, files) {
+    if (files.length === 0) {
+        return {
+            files,
+            pathMap: new Map(),
+            cleanup: () => undefined
+        };
+    }
+    const tempDir = fs.mkdtempSync(path.join(repoRoot, ".stego-tooling-"));
+    const pathMap = new Map();
+    const preparedFiles = [];
+    for (let index = 0; index < files.length; index += 1) {
+        const filePath = files[index];
+        const raw = fs.readFileSync(filePath, "utf8");
+        const relativePath = path.relative(repoRoot, filePath);
+        const parsed = parseCommentAppendix(raw);
+        const sanitized = parsed.contentWithoutComments.endsWith("\n")
+            ? parsed.contentWithoutComments
+            : `${parsed.contentWithoutComments}\n`;
+        const relativeTarget = relativePath.startsWith("..")
+            ? `external/file-${index + 1}-${path.basename(filePath)}`
+            : relativePath;
+        const targetPath = path.join(tempDir, relativeTarget);
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.writeFileSync(targetPath, sanitized, "utf8");
+        preparedFiles.push(targetPath);
+        pathMap.set(targetPath, filePath);
+    }
+    return {
+        files: preparedFiles,
+        pathMap,
+        cleanup: () => {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    };
+}
+function remapToolOutputPaths(output, pathMap, repoRoot) {
+    if (!output || pathMap.size === 0) {
+        return output;
+    }
+    const root = repoRoot || process.cwd();
+    let mapped = output;
+    for (const [preparedPath, originalPath] of pathMap.entries()) {
+        if (preparedPath === originalPath) {
+            continue;
+        }
+        mapped = mapped.split(preparedPath).join(originalPath);
+        const preparedRelative = path.relative(root, preparedPath);
+        const originalRelative = path.relative(root, originalPath);
+        const preparedRelativeNormalized = preparedRelative.split(path.sep).join("/");
+        const originalRelativeNormalized = originalRelative.split(path.sep).join("/");
+        mapped = mapped.split(preparedRelative).join(originalRelative);
+        mapped = mapped.split(preparedRelativeNormalized).join(originalRelativeNormalized);
+    }
+    return mapped;
+}
+function resolveCommand(repoRoot, command) {
+    const localCommandPath = path.join(repoRoot, "node_modules", ".bin", process.platform === "win32" ? `${command}.cmd` : command);
+    if (fs.existsSync(localCommandPath)) {
+        return localCommandPath;
+    }
+    return null;
+}
+function compactToolOutput(stdout, stderr) {
+    const text = `${stdout || ""}\n${stderr || ""}`.trim();
+    if (!text) {
+        return "No details provided by tool.";
+    }
+    return text
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .slice(0, 4)
+        .join(" | ");
+}
+function readJson(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Missing JSON file: ${filePath}`);
+    }
+    const raw = fs.readFileSync(filePath, "utf8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON at ${filePath}: ${message}`);
+    }
+}
+function readBooleanOption(options, key) {
+    return options[key] === true;
+}
+function makeIssue(level, category, message, file = null, line = null) {
+    return { level, category, message, file, line };
+}

package/dist/stego-cli/src/modules/quality/application/stage-check.js

@@ -0,0 +1,87 @@
+import { getStageRank, isStageName } from "../../../../../shared/src/domain/stages/index.js";
+import { inspectProject } from "./inspect-project.js";
+import { collectSpineWordsForSpellcheck, runCSpell, runMarkdownlint } from "./lint-runner.js";
+export function runStageCheck(project, stage, onlyFile) {
+    const policy = resolveStagePolicy(project, stage);
+    const report = inspectProject(project, { onlyFile });
+    const issues = [...report.issues];
+    const minimumRank = getStageRank(policy.minimumChapterStatus);
+    for (const chapter of report.chapters) {
+        if (!isStageName(chapter.status)) {
+            continue;
+        }
+        const chapterRank = getStageRank(chapter.status);
+        if (chapterRank < minimumRank) {
+            issues.push(makeIssue("error", "stage", `File status '${chapter.status}' is below required stage '${policy.minimumChapterStatus}'.`, chapter.relativePath));
+        }
+        if (stage === "final" && chapter.status !== "final") {
+            issues.push(makeIssue("error", "stage", "Final stage requires all chapters to be status 'final'.", chapter.relativePath));
+        }
+        if (policy.requireResolvedComments) {
+            const unresolvedComments = chapter.comments.filter((comment) => !comment.resolved);
+            if (unresolvedComments.length > 0) {
+                const unresolvedLabel = unresolvedComments.slice(0, 5).map((comment) => comment.id).join(", ");
+                const remainder = unresolvedComments.length > 5 ? ` (+${unresolvedComments.length - 5} more)` : "";
+                issues.push(makeIssue("error", "comments", `Unresolved comments (${unresolvedComments.length}): ${unresolvedLabel}${remainder}. Resolve or clear comments before stage '${stage}'.`, chapter.relativePath));
+            }
+        }
+    }
+    if (policy.requireSpine) {
+        if (report.spineState.categories.length === 0) {
+            issues.push(makeIssue("error", "continuity", "No spine categories found. Add at least one category under spine/<category>/ before this stage."));
+        }
+        for (const spineIssue of report.issues.filter((issue) => issue.category === "continuity")) {
+            if (spineIssue.message.startsWith("Missing spine directory")) {
+                issues.push({ ...spineIssue, level: "error" });
+            }
+        }
+    }
+    if (policy.enforceLocalLinks) {
+        for (const linkIssue of issues.filter((issue) => issue.category === "links" && issue.level !== "error")) {
+            linkIssue.level = "error";
+            linkIssue.message = `${linkIssue.message} (strict in stage '${stage}')`;
+        }
+    }
+    const chapterPaths = report.chapters.map((chapter) => chapter.path);
+    const spineWords = collectSpineWordsForSpellcheck(report.spineState.entriesByCategory);
+    if (policy.enforceMarkdownlint) {
+        issues.push(...runMarkdownlint(project, chapterPaths, true, "manuscript"));
+    }
+    else {
+        issues.push(...runMarkdownlint(project, chapterPaths, false, "manuscript"));
+    }
+    if (policy.enforceCSpell) {
+        issues.push(...runCSpell(project, chapterPaths, true, spineWords));
+    }
+    else {
+        issues.push(...runCSpell(project, chapterPaths, false, spineWords));
+    }
+    return { chapters: report.chapters, issues };
+}
+function resolveStagePolicy(project, stage) {
+    if (!isStageName(stage)) {
+        throw new Error(`Unknown stage '${stage}'. Allowed: ${Object.keys(project.workspace.config.stagePolicies).join(", ")}.`);
+    }
+    const rawPolicy = project.workspace.config.stagePolicies[stage];
+    if (!isStagePolicy(rawPolicy)) {
+        throw new Error(`Invalid stage policy for '${stage}' in stego.config.json.`);
+    }
+    return rawPolicy;
+}
+function isStagePolicy(value) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    return isStageName(String(value.minimumChapterStatus))
+        && typeof value.requireSpine === "boolean"
+        && typeof value.enforceMarkdownlint === "boolean"
+        && typeof value.enforceCSpell === "boolean"
+        && typeof value.enforceLocalLinks === "boolean"
+        && (value.requireResolvedComments == null || typeof value.requireResolvedComments === "boolean");
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function makeIssue(level, category, message, file = null, line = null) {
+    return { level, category, message, file, line };
+}

package/dist/stego-cli/src/modules/quality/commands/check-stage.js

@@ -0,0 +1,54 @@
+import { writeText } from "../../../app/output-renderer.js";
+import { resolveProjectContext } from "../../project/index.js";
+import { resolveWorkspaceContext } from "../../workspace/index.js";
+import { formatIssues, issueHasErrors } from "../application/inspect-project.js";
+import { runStageCheck } from "../application/stage-check.js";
+export function registerCheckStageCommand(registry) {
+    registry.register({
+        name: "check-stage",
+        description: "Run stage-specific quality gates",
+        allowUnknownOptions: true,
+        options: [
+            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "--stage <stage>", description: "draft|revise|line-edit|proof|final" },
+            { flags: "--file <path>", description: "Project-relative manuscript path" },
+            { flags: "--root <path>", description: "Workspace root path" }
+        ],
+        action: (context) => {
+            const project = resolveProjectContext({
+                workspace: resolveWorkspaceContext({
+                    cwd: context.cwd,
+                    rootOption: readStringOption(context.options, "root")
+                }),
+                cwd: context.cwd,
+                env: context.env,
+                explicitProjectId: readStringOption(context.options, "project")
+            });
+            const stage = readStringOption(context.options, "stage") || "draft";
+            const requestedFile = readStringOption(context.options, "file");
+            const report = runStageCheck(project, stage, requestedFile);
+            for (const line of formatIssues(report.issues)) {
+                writeText(line);
+            }
+            if (issueHasErrors(report.issues)) {
+                process.exitCode = 1;
+                return;
+            }
+            if (requestedFile && report.chapters.length === 1) {
+                writeText(`Stage check passed for '${report.chapters[0].relativePath}' at stage '${stage}'.`);
+                return;
+            }
+            writeText(`Stage check passed for '${project.id}' at stage '${stage}'.`);
+        }
+    });
+}
+function readStringOption(options, key) {
+    const value = options[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}

package/dist/stego-cli/src/modules/quality/commands/lint.js

@@ -0,0 +1,51 @@
+import { writeText } from "../../../app/output-renderer.js";
+import { resolveProjectContext } from "../../project/index.js";
+import { resolveWorkspaceContext } from "../../workspace/index.js";
+import { formatIssues, issueHasErrors } from "../application/inspect-project.js";
+import { formatLintSelection, resolveLintSelection, runProjectLint } from "../application/lint-runner.js";
+export function registerLintCommand(registry) {
+    registry.register({
+        name: "lint",
+        description: "Run markdown and spelling checks",
+        allowUnknownOptions: true,
+        options: [
+            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "--manuscript", description: "Lint manuscript files only" },
+            { flags: "--spine", description: "Lint spine/notes files only" },
+            { flags: "--root <path>", description: "Workspace root path" }
+        ],
+        action: (context) => {
+            const project = resolveProjectContext({
+                workspace: resolveWorkspaceContext({
+                    cwd: context.cwd,
+                    rootOption: readStringOption(context.options, "root")
+                }),
+                cwd: context.cwd,
+                env: context.env,
+                explicitProjectId: readStringOption(context.options, "project")
+            });
+            const selection = resolveLintSelection(context.options);
+            const result = runProjectLint(project, selection);
+            for (const line of formatIssues(result.issues)) {
+                writeText(line);
+            }
+            if (issueHasErrors(result.issues)) {
+                process.exitCode = 1;
+                return;
+            }
+            const scopeLabel = formatLintSelection(selection);
+            const fileLabel = result.fileCount === 1 ? "file" : "files";
+            writeText(`Lint passed for '${project.id}' (${scopeLabel}, ${result.fileCount} ${fileLabel}).`);
+        }
+    });
+}
+function readStringOption(options, key) {
+    const value = options[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}

package/dist/stego-cli/src/modules/quality/commands/validate.js

@@ -0,0 +1,50 @@
+import { writeText } from "../../../app/output-renderer.js";
+import { resolveProjectContext } from "../../project/index.js";
+import { resolveWorkspaceContext } from "../../workspace/index.js";
+import { formatIssues, inspectProject, issueHasErrors } from "../application/inspect-project.js";
+export function registerValidateCommand(registry) {
+    registry.register({
+        name: "validate",
+        description: "Validate manuscript and project state",
+        allowUnknownOptions: true,
+        options: [
+            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "--file <path>", description: "Project-relative manuscript path" },
+            { flags: "--root <path>", description: "Workspace root path" }
+        ],
+        action: (context) => {
+            const project = resolveProjectContext({
+                workspace: resolveWorkspaceContext({
+                    cwd: context.cwd,
+                    rootOption: readStringOption(context.options, "root")
+                }),
+                cwd: context.cwd,
+                env: context.env,
+                explicitProjectId: readStringOption(context.options, "project")
+            });
+            const report = inspectProject(project, { onlyFile: readStringOption(context.options, "file") });
+            for (const line of formatIssues(report.issues)) {
+                writeText(line);
+            }
+            if (issueHasErrors(report.issues)) {
+                process.exitCode = 1;
+                return;
+            }
+            if (report.chapters.length === 1) {
+                writeText(`Validation passed for '${report.chapters[0].relativePath}'.`);
+                return;
+            }
+            writeText(`Validation passed for '${project.id}'.`);
+        }
+    });
+}
+function readStringOption(options, key) {
+    const value = options[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}

package/dist/stego-cli/src/modules/quality/domain/issues.js

@@ -0,0 +1 @@
+export {};

package/dist/stego-cli/src/modules/quality/domain/policies.js

@@ -0,0 +1 @@
+export {};

package/dist/stego-cli/src/modules/quality/index.js

@@ -0,0 +1,14 @@
+import { registerValidateCommand } from "./commands/validate.js";
+import { registerLintCommand } from "./commands/lint.js";
+import { registerCheckStageCommand } from "./commands/check-stage.js";
+export const qualityModule = {
+    registerCommands(registry) {
+        registerValidateCommand(registry);
+        registerLintCommand(registry);
+        registerCheckStageCommand(registry);
+    }
+};
+export * from "./types.js";
+export * from "./application/inspect-project.js";
+export * from "./application/stage-check.js";
+export * from "./application/lint-runner.js";

package/dist/stego-cli/src/modules/quality/infra/cspell-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/stego-cli/src/modules/quality/infra/markdownlint-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/stego-cli/src/modules/quality/types.js

@@ -0,0 +1 @@
+export {};