@lsctech/polaris 0.1.0

package/dist/smartdocs-engine/audit.test.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const vitest_1 = require("vitest");
+const audit_js_1 = require("./audit.js");
+function makeGitRepo() {
+    const repoRoot = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "polaris-audit-"));
+    (0, node_child_process_1.execFileSync)("git", ["init"], { cwd: repoRoot });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.email", "test@test.com"], { cwd: repoRoot });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.name", "Test"], { cwd: repoRoot });
+    return repoRoot;
+}
+function addTrackedFile(repoRoot, relPath, content = "# Doc\n\nContent") {
+    const dir = relPath.includes("/")
+        ? (0, node_path_1.join)(repoRoot, relPath.split("/").slice(0, -1).join("/"))
+        : repoRoot;
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, relPath), content, "utf-8");
+    (0, node_child_process_1.execFileSync)("git", ["add", relPath], { cwd: repoRoot });
+}
+(0, vitest_1.describe)("auditIngestRiskSurface", () => {
+    (0, vitest_1.it)("flags endpoint artifacts as HIGH risk", () => {
+        const repoRoot = makeGitRepo();
+        addTrackedFile(repoRoot, ".claude/SKILL.md", "# Skill doc\n");
+        const result = (0, audit_js_1.auditIngestRiskSurface)(repoRoot);
+        const highIngest = result.findings.filter((f) => f.risk === "HIGH" && f.pipelineStage === "ingest" && f.filePath === ".claude/SKILL.md");
+        (0, vitest_1.expect)(highIngest.length).toBe(1);
+        (0, vitest_1.expect)(highIngest[0].currentProtection).toBe("isIngestIneligible");
+        (0, vitest_1.expect)(result.summary.high).toBeGreaterThanOrEqual(1);
+        (0, vitest_1.expect)(result.summary.protectedBySmartdocIgnore).toBeGreaterThanOrEqual(1);
+    });
+    (0, vitest_1.it)("flags doctrine-candidate endpoint artifacts as HIGH with pipelineStage classify", () => {
+        const repoRoot = makeGitRepo();
+        // Content that classifyDoc will return "doctrine-candidate" for
+        const doctrineContent = "# Doctrine Rule\n\nYou must always check eligibility. Never silently fail.\n";
+        addTrackedFile(repoRoot, ".claude/POLARIS-doctrine.md", doctrineContent);
+        const result = (0, audit_js_1.auditIngestRiskSurface)(repoRoot);
+        const classifyFindings = result.findings.filter((f) => f.risk === "HIGH" &&
+            f.pipelineStage === "classify" &&
+            f.filePath === ".claude/POLARIS-doctrine.md");
+        (0, vitest_1.expect)(classifyFindings.length).toBe(1);
+        (0, vitest_1.expect)(classifyFindings[0].currentProtection).toBe("isIngestIneligible");
+        (0, vitest_1.expect)(classifyFindings[0].proposedEnforcementPoint).toContain("classifyDoc");
+    });
+    (0, vitest_1.it)("returns valid AuditResult shape with no tracked files", () => {
+        const repoRoot = makeGitRepo();
+        const result = (0, audit_js_1.auditIngestRiskSurface)(repoRoot);
+        (0, vitest_1.expect)(result).toHaveProperty("scanDate");
+        (0, vitest_1.expect)(result).toHaveProperty("repoRoot");
+        (0, vitest_1.expect)(result).toHaveProperty("findings");
+        (0, vitest_1.expect)(result).toHaveProperty("summary");
+        (0, vitest_1.expect)(Array.isArray(result.findings)).toBe(true);
+        (0, vitest_1.expect)(typeof result.summary.high).toBe("number");
+        (0, vitest_1.expect)(typeof result.summary.medium).toBe("number");
+        (0, vitest_1.expect)(typeof result.summary.low).toBe("number");
+        (0, vitest_1.expect)(typeof result.summary.protectedBySmartdocIgnore).toBe("number");
+        (0, vitest_1.expect)(typeof result.summary.alreadyProtected).toBe("number");
+        (0, vitest_1.expect)(result.summary.alreadyProtected).toBe(result.summary.protectedBySmartdocIgnore);
+    });
+    (0, vitest_1.it)("flags generated summary files as MEDIUM risk", () => {
+        const repoRoot = makeGitRepo();
+        addTrackedFile(repoRoot, "docs/sprint-summary.md", "# Sprint summary\n");
+        const result = (0, audit_js_1.auditIngestRiskSurface)(repoRoot);
+        const mediumFindings = result.findings.filter((f) => f.risk === "MEDIUM" && f.filePath === "docs/sprint-summary.md");
+        (0, vitest_1.expect)(mediumFindings.length).toBe(1);
+        (0, vitest_1.expect)(mediumFindings[0].pipelineStage).toBe("ingest");
+    });
+});
+(0, vitest_1.describe)("formatAuditMarkdown", () => {
+    (0, vitest_1.it)("produces markdown with summary table and findings sections", () => {
+        const result = {
+            scanDate: "2026-05-26T00:00:00.000Z",
+            repoRoot: "/repo",
+            findings: [
+                {
+                    filePath: ".claude/SKILL.md",
+                    risk: "HIGH",
+                    reason: "Endpoint artifact matched by .smartdocignore default patterns — ingest would be blocked but file is tracked",
+                    pipelineStage: "ingest",
+                    currentProtection: "isIngestIneligible",
+                    proposedEnforcementPoint: "smartdoc-ignore check in ingestDocs()",
+                },
+                {
+                    filePath: "docs/overview.md",
+                    risk: "MEDIUM",
+                    reason: "Generated summary or index file — ingest risk if not protected",
+                    pipelineStage: "ingest",
+                    currentProtection: null,
+                    proposedEnforcementPoint: "smartdoc-ignore pattern or explicit check",
+                },
+            ],
+            summary: {
+                high: 1,
+                medium: 1,
+                low: 0,
+                protectedBySmartdocIgnore: 1,
+                alreadyProtected: 1,
+            },
+        };
+        const md = (0, audit_js_1.formatAuditMarkdown)(result);
+        (0, vitest_1.expect)(md).toContain("# Polaris Smart Docs — Ingest Risk Audit");
+        (0, vitest_1.expect)(md).toContain("HIGH | 1");
+        (0, vitest_1.expect)(md).toContain("MEDIUM | 1");
+        (0, vitest_1.expect)(md).toContain(".claude/SKILL.md");
+        (0, vitest_1.expect)(md).toContain("docs/overview.md");
+        (0, vitest_1.expect)(md).toContain("## HIGH Risk Findings");
+        (0, vitest_1.expect)(md).toContain("## MEDIUM Risk Findings");
+    });
+    (0, vitest_1.it)("outputs no-findings message when findings is empty", () => {
+        const result = {
+            scanDate: "2026-05-26T00:00:00.000Z",
+            repoRoot: "/repo",
+            findings: [],
+            summary: { high: 0, medium: 0, low: 0, protectedBySmartdocIgnore: 0, alreadyProtected: 0 },
+        };
+        const md = (0, audit_js_1.formatAuditMarkdown)(result);
+        (0, vitest_1.expect)(md).toContain("No findings");
+    });
+});

package/dist/smartdocs-engine/canon-check.js

@@ -0,0 +1,340 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCanonCheck = runCanonCheck;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// Modal verbs that indicate behavioral assertions in doctrine/spec files
+const MODAL_VERBS = /\b(must|never|always|should|required|requires|shall)\b/i;
+// Domains matched by filename keywords
+const DOMAIN_KEYWORDS = ["loop", "map", "finalize", "config", "cli", "docs"];
+/** Walk up from `startDir` to `repoRoot` looking for the nearest POLARIS.md */
+function findNearestPolarisMd(startDir, repoRoot) {
+    let dir = (0, node_path_1.resolve)(startDir);
+    const root = (0, node_path_1.resolve)(repoRoot);
+    let searching = true;
+    while (searching) {
+        const candidate = (0, node_path_1.join)(dir, "POLARIS.md");
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+        if (dir === root)
+            break;
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir) {
+            searching = false;
+            break;
+        } // filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/** Collect all relevant canon files for the given changed files */
+function locateCanonFiles(changedFiles, repoRoot) {
+    const canon = new Set();
+    // POLARIS.md files — nearest ancestor for each changed file
+    for (const f of changedFiles) {
+        if ((0, node_path_1.basename)(f).toLowerCase() === "summary.md")
+            continue;
+        const absFile = (0, node_path_1.resolve)(repoRoot, f);
+        const startDir = (0, node_path_1.dirname)(absFile);
+        const polarisMd = findNearestPolarisMd(startDir, repoRoot);
+        if (polarisMd)
+            canon.add(polarisMd);
+    }
+    // Active doctrine
+    const doctrineDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "active");
+    if ((0, node_fs_1.existsSync)(doctrineDir)) {
+        for (const f of (0, node_fs_1.readdirSync)(doctrineDir)) {
+            if (f.endsWith(".md") && (0, node_path_1.basename)(f).toLowerCase() !== "summary.md")
+                canon.add((0, node_path_1.join)(doctrineDir, f));
+        }
+    }
+    // Active and implemented specs — filtered by domain keyword overlap
+    const changedDomains = new Set();
+    for (const f of changedFiles) {
+        if ((0, node_path_1.basename)(f).toLowerCase() === "summary.md")
+            continue;
+        for (const kw of DOMAIN_KEYWORDS) {
+            if (f.toLowerCase().includes(kw))
+                changedDomains.add(kw);
+        }
+    }
+    for (const specSubdir of ["active", "implemented"]) {
+        const specDir = (0, node_path_1.join)(repoRoot, "docs", "specs", specSubdir);
+        if (!(0, node_fs_1.existsSync)(specDir))
+            continue;
+        for (const f of (0, node_fs_1.readdirSync)(specDir)) {
+            if (!f.endsWith(".md") || (0, node_path_1.basename)(f).toLowerCase() === "summary.md")
+                continue;
+            const lower = f.toLowerCase();
+            const matches = changedDomains.size === 0 || Array.from(changedDomains).some((kw) => lower.includes(kw));
+            if (matches)
+                canon.add((0, node_path_1.join)(specDir, f));
+        }
+    }
+    return canon;
+}
+/** Extract bullet-point lines from a named markdown section */
+function extractSection(content, sectionHeader) {
+    const lines = content.split("\n");
+    const result = [];
+    let inSection = false;
+    for (const line of lines) {
+        if (line.startsWith("##") && line.toLowerCase().includes(sectionHeader.toLowerCase())) {
+            inSection = true;
+            continue;
+        }
+        if (inSection) {
+            if (line.startsWith("##"))
+                break; // next section
+            const trimmed = line.trim();
+            if (trimmed.startsWith("-") || trimmed.startsWith("*")) {
+                result.push(trimmed.replace(/^[-*]\s*/, ""));
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Check if a POLARIS.md rule explicitly names a changed file as deleted/removed while it still exists.
+ * This is the primary `stale-implementation` trigger for MVP.
+ */
+function checkPolarisMd(canonFile, changedFiles, repoRoot) {
+    const conflicts = [];
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)(canonFile, "utf-8");
+    }
+    catch {
+        return conflicts;
+    }
+    const editingRules = extractSection(content, "editing rules");
+    const archAssumptions = extractSection(content, "architecture assumptions");
+    const allRules = [...editingRules, ...archAssumptions];
+    for (const rule of allRules) {
+        const lower = rule.toLowerCase();
+        // Detect rules that say something is deleted/removed but the file still exists
+        const isDeleted = /\b(deleted|removed|no longer exists|do not use)\b/.test(lower);
+        if (!isDeleted)
+            continue;
+        for (const changedFile of changedFiles) {
+            const fileBasename = (0, node_path_1.basename)(changedFile);
+            if (lower.includes(fileBasename.toLowerCase()) && (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, changedFile))) {
+                // Determine conflict type based on rule text and changed file
+                let conflictType = "stale-implementation";
+                const ext = changedFile.split(".").pop()?.toLowerCase() ?? "";
+                const isDocFile = ext === "md" || changedFile.startsWith("docs/");
+                const hasDocKeywords = /\b(doc|documentation|readme|guide|spec)\b/i.test(lower);
+                const hasCandidateKeywords = /\b(candidate|divergence|proposal)\b/i.test(lower);
+                if (isDocFile || hasDocKeywords) {
+                    conflictType = "stale-docs";
+                }
+                else if (hasCandidateKeywords) {
+                    conflictType = "candidate-divergence";
+                }
+                conflicts.push({
+                    type: conflictType,
+                    canonFile,
+                    statement: rule,
+                    changedFile,
+                    detail: `POLARIS.md states "${fileBasename}" is deleted/removed but the file still exists`,
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+/**
+ * Check doctrine/spec files for modal-verb assertions that directly contradict changed files.
+ * MVP: only flag stale-implementation when a named file/command is explicitly asserted to
+ * exist/be-required but is missing, or asserted as deleted while still present.
+ */
+function checkDocFile(canonFile, changedFiles, repoRoot) {
+    if ((0, node_path_1.basename)(canonFile).toLowerCase() === "summary.md")
+        return [];
+    const conflicts = [];
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)(canonFile, "utf-8");
+    }
+    catch {
+        return conflicts;
+    }
+    const lines = content.split("\n");
+    for (const line of lines) {
+        if (!MODAL_VERBS.test(line))
+            continue;
+        const lower = line.toLowerCase();
+        // Only flag lines that name a specific file/command that should exist but doesn't
+        const deletedAssertion = /\b(deleted|removed|no longer exists)\b/.test(lower);
+        if (!deletedAssertion)
+            continue;
+        for (const changedFile of changedFiles) {
+            const fileBasename = (0, node_path_1.basename)(changedFile);
+            if (lower.includes(fileBasename.toLowerCase()) && (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, changedFile))) {
+                conflicts.push({
+                    type: "stale-implementation",
+                    canonFile,
+                    statement: line.trim(),
+                    changedFile,
+                    detail: `Canon asserts "${fileBasename}" is deleted/removed but file still exists`,
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+function appendTelemetry(telemetryFile, event) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+        (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+    }
+    catch {
+        // Non-fatal: telemetry write failure should not block operation
+    }
+}
+/**
+ * Run the canon reconciliation check.
+ *
+ * Emits `canon-check-start` and either `canon-check-result` or `canon-conflict-halt`
+ * to the telemetry file. Returns the result for the caller to act on.
+ *
+ * Note: This function does NOT call process.exit. Callers are responsible for
+ * halting execution based on the returned outcome.
+ */
+function runCanonCheck(options) {
+    const { repoRoot, changedFiles, childId, runId, telemetryFile } = options;
+    const canonFilesSet = locateCanonFiles(changedFiles, repoRoot);
+    const canonFilesInspected = canonFilesSet.size;
+    appendTelemetry(telemetryFile, {
+        event: "canon-check-start",
+        run_id: runId,
+        child_id: childId ?? null,
+        canon_files_inspected: canonFilesInspected,
+        changed_files_count: changedFiles.length,
+        timestamp: new Date().toISOString(),
+    });
+    if (canonFilesInspected === 0 || changedFiles.length === 0) {
+        const result = { outcome: "aligned", conflicts: [], canonFilesInspected };
+        appendTelemetry(telemetryFile, {
+            event: "canon-check-result",
+            run_id: runId,
+            child_id: childId ?? null,
+            outcome: "aligned",
+            conflicts: [],
+            timestamp: new Date().toISOString(),
+        });
+        return result;
+    }
+    const allConflicts = [];
+    for (const canonFile of canonFilesSet) {
+        const fileBasename = (0, node_path_1.basename)(canonFile);
+        const isPolarisMd = fileBasename === "POLARIS.md";
+        const fileConflicts = isPolarisMd
+            ? checkPolarisMd(canonFile, changedFiles, repoRoot)
+            : checkDocFile(canonFile, changedFiles, repoRoot);
+        allConflicts.push(...fileConflicts);
+    }
+    // Classify outcome: stale-implementation wins; then stale-docs; then candidate-divergence; else aligned
+    let outcome = "aligned";
+    if (allConflicts.some((c) => c.type === "stale-implementation")) {
+        outcome = "stale-implementation";
+    }
+    else if (allConflicts.some((c) => c.type === "stale-docs")) {
+        outcome = "stale-docs";
+    }
+    else if (allConflicts.some((c) => c.type === "candidate-divergence")) {
+        outcome = "candidate-divergence";
+    }
+    const result = { outcome, conflicts: allConflicts, canonFilesInspected };
+    if (outcome === "stale-implementation") {
+        const first = allConflicts.find((c) => c.type === "stale-implementation");
+        appendTelemetry(telemetryFile, {
+            event: "canon-conflict-halt",
+            run_id: runId,
+            child_id: childId ?? null,
+            reason: first.detail,
+            canon_file: first.canonFile,
+            conflicting_statement: first.statement,
+            missing_or_differing: first.changedFile,
+            suggested_resolution: "Update the canon file to reflect current state, or remove/fix the conflicting assertion",
+            timestamp: new Date().toISOString(),
+        });
+    }
+    else {
+        appendTelemetry(telemetryFile, {
+            event: "canon-check-result",
+            run_id: runId,
+            child_id: childId ?? null,
+            outcome,
+            conflicts: allConflicts,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // For non-blocking outcomes, write draft docs as specified
+    if (outcome === "stale-docs") {
+        writeStaleDraftDocs(allConflicts.filter((c) => c.type === "stale-docs"), repoRoot, childId);
+    }
+    else if (outcome === "candidate-divergence") {
+        writeCandidateDraftDocs(allConflicts.filter((c) => c.type === "candidate-divergence"), repoRoot, childId);
+    }
+    return result;
+}
+function writeStaleDraftDocs(conflicts, repoRoot, childId) {
+    const rawDir = (0, node_path_1.join)(repoRoot, "docs", "raw");
+    try {
+        (0, node_fs_1.mkdirSync)(rawDir, { recursive: true });
+        for (const conflict of conflicts) {
+            const slug = (0, node_path_1.basename)(conflict.canonFile).replace(/\.md$/, "");
+            const date = new Date().toISOString().slice(0, 10);
+            const filename = `stale-flag-${slug}-${date}.md`;
+            const path = (0, node_path_1.join)(rawDir, filename);
+            if (!(0, node_fs_1.existsSync)(path)) {
+                (0, node_fs_1.writeFileSync)(path, [
+                    `# Stale Doc Flag`,
+                    ``,
+                    `**Canon file:** ${conflict.canonFile}`,
+                    `**Triggering file:** ${conflict.changedFile}`,
+                    `**What appears outdated:** ${conflict.statement}`,
+                    `**Detail:** ${conflict.detail}`,
+                    `**Flagged by:** ${childId ?? "finalize"}`,
+                    `**Date:** ${new Date().toISOString()}`,
+                ].join("\n"), "utf-8");
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
+function writeCandidateDraftDocs(conflicts, repoRoot, childId) {
+    const candidateDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate");
+    try {
+        (0, node_fs_1.mkdirSync)(candidateDir, { recursive: true });
+        for (const conflict of conflicts) {
+            const slug = (0, node_path_1.basename)(conflict.canonFile).replace(/\.md$/, "");
+            const date = new Date().toISOString().slice(0, 10);
+            const filename = `${slug}-${date}.draft.md`;
+            const path = (0, node_path_1.join)(candidateDir, filename);
+            if (!(0, node_fs_1.existsSync)(path)) {
+                (0, node_fs_1.writeFileSync)(path, [
+                    `---`,
+                    `status: candidate`,
+                    `source: ${conflict.canonFile}`,
+                    `proposed-by: ${childId ?? "unknown"}`,
+                    `proposed-at: ${new Date().toISOString()}`,
+                    `---`,
+                    ``,
+                    `# Candidate Divergence Draft`,
+                    ``,
+                    `**Source canon file:** ${conflict.canonFile}`,
+                    `**Conflicting statement:** ${conflict.statement}`,
+                    `**Changed file:** ${conflict.changedFile}`,
+                    `**Detail:** ${conflict.detail}`,
+                ].join("\n"), "utf-8");
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}