@lsctech/polaris 0.1.0

package/dist/smartdocs-engine/smartdoc-ignore.js

@@ -0,0 +1,258 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLARIS_RUNTIME_COGNITION_DIRS = exports.HIDDEN_SYSTEM_FOLDERS = exports.AGENT_COGNITION_FOLDERS = exports.RUNTIME_EXCLUDED_DIR_PATTERNS = exports.parseSmarDocIgnore = exports.DEFAULT_SMARTDOCIGNORE_PATTERNS = void 0;
+exports.parseSmartDocIgnore = parseSmartDocIgnore;
+exports.isIngestIneligible = isIngestIneligible;
+exports.isDirectoryEligible = isDirectoryEligible;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ignore_1 = __importDefault(require("ignore"));
+exports.DEFAULT_SMARTDOCIGNORE_PATTERNS = [
+    ".taskchain_artifacts/**",
+    ".polaris/**",
+    ".polaris/graph/**",
+    ".codex/**",
+    ".claude/**",
+    ".github/**",
+    ".windsurf/**",
+    ".agents/**",
+    "smartdocs/doctrine/**",
+    "smartdocs/specs/active/**",
+    "smartdocs/specs/implemented/**",
+    "smartdocs/specs/superseded/**",
+    "smartdocs/architecture/**",
+    "smartdocs/decisions/**",
+    "smartdocs/audits/**",
+    "smartdocs/runtime/**",
+    "smartdocs/integrations/**",
+    "smartdocs/.obsidian/**",
+    "generated/**",
+    "**/generated/**",
+    "summaries/**",
+    "**/summaries/**",
+    "README.md",
+    "**/README.md",
+    "AGENTS.md",
+    "**/AGENTS.md",
+    "CLAUDE.md",
+    "**/CLAUDE.md",
+    "GEMINI.md",
+    "**/GEMINI.md",
+    "POLARIS.md",
+    "**/POLARIS.md",
+    "SUMMARY.md",
+    "**/SUMMARY.md",
+    "*.sqlite",
+    "*.db",
+];
+function toRepoRelativePath(filePath, repoRoot) {
+    const resolvedRoot = (0, node_path_1.resolve)(repoRoot);
+    const resolvedPath = (0, node_path_1.resolve)(resolvedRoot, filePath);
+    return (0, node_path_1.relative)(resolvedRoot, resolvedPath).replace(/\\/g, "/");
+}
+function parseSmartDocIgnore(repoRoot) {
+    const ig = (0, ignore_1.default)();
+    const ignorePath = (0, node_path_1.resolve)(repoRoot, ".smartdocignore");
+    if ((0, node_fs_1.existsSync)(ignorePath)) {
+        ig.add((0, node_fs_1.readFileSync)(ignorePath, "utf-8"));
+    }
+    ig.add(exports.DEFAULT_SMARTDOCIGNORE_PATTERNS);
+    return ig;
+}
+exports.parseSmarDocIgnore = parseSmartDocIgnore;
+function isIngestIneligible(filePath, repoRoot) {
+    const relPath = toRepoRelativePath(filePath, repoRoot);
+    if (parseSmartDocIgnore(repoRoot).ignores(relPath)) {
+        return {
+            ineligible: true,
+            reason: `ignored by .smartdocignore/defaults: ${relPath}`,
+        };
+    }
+    return { ineligible: false };
+}
+/**
+ * Runtime/build artifact directories that are permanently excluded from Smart Docs.
+ * These are generated files, dependencies, or ephemeral runtime data.
+ */
+exports.RUNTIME_EXCLUDED_DIR_PATTERNS = [
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".git",
+    ".antigravitycli",
+    ".taskchain_artifacts",
+    "generated",
+    "summaries",
+    "test-output",
+    "test_output",
+    "test-results",
+    "test_results",
+    "fixtures",
+    "fixture",
+    "__snapshots__",
+    "__fixtures__",
+    ".turbo",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    ".vercel",
+    ".netlify",
+    ".cache",
+    ".parcel-cache",
+    ".webpack",
+    ".rollup",
+    ".vite",
+    ".idea",
+    ".vscode",
+    ".nova",
+];
+/**
+ * Agent/runtime cognition folders that are temporarily excluded by default.
+ * These are not "junk" - they contain valid agent context, but are skipped
+ * to avoid noise in default seeding. Can be included via --include-agent-folders.
+ */
+exports.AGENT_COGNITION_FOLDERS = [
+    ".codex",
+    ".claude",
+    ".agents",
+];
+/**
+ * Other hidden/system folders that are excluded by default.
+ * These are typically IDE/system folders, not agent cognition.
+ */
+exports.HIDDEN_SYSTEM_FOLDERS = [
+    ".github",
+    ".windsurf",
+];
+exports.POLARIS_RUNTIME_COGNITION_DIRS = [
+    ".polaris",
+    ".polaris/bootstrap",
+    ".polaris/clusters",
+    ".polaris/map",
+    ".polaris/runs",
+];
+const POLARIS_RUNTIME_GENERATED_DIR_PREFIXES = [
+    ".polaris/bootstrap/",
+    ".polaris/clusters/",
+    ".polaris/map/",
+    ".polaris/runs/",
+];
+function getPolarisDirectoryEligibility(relPath, opts) {
+    if (exports.POLARIS_RUNTIME_COGNITION_DIRS.includes(relPath)) {
+        return { eligible: true, category: "eligible" };
+    }
+    for (const prefix of POLARIS_RUNTIME_GENERATED_DIR_PREFIXES) {
+        if (relPath.startsWith(prefix)) {
+            return {
+                eligible: false,
+                reason: `generated Polaris runtime directory excluded: ${relPath}`,
+                category: "runtime",
+            };
+        }
+    }
+    if (relPath.startsWith(".polaris/")) {
+        if (opts.includeHidden) {
+            return { eligible: true, category: "eligible" };
+        }
+        return {
+            eligible: false,
+            reason: `hidden Polaris directory (use --include-hidden to include): ${relPath}`,
+            category: "hidden",
+        };
+    }
+    return null;
+}
+/**
+ * Check if a directory is eligible for Smart Docs coverage.
+ * Returns eligible: false for build artifacts, dependency folders, and ignored directories.
+ */
+function isDirectoryEligible(dirPath, repoRoot, opts = {}) {
+    const relPath = toRepoRelativePath(dirPath, repoRoot);
+    const dirName = relPath.split("/").pop() || relPath;
+    // Special handling for root directory
+    if (opts.isRoot) {
+        if (opts.skipRoot !== false) {
+            return {
+                eligible: false,
+                reason: "root skipped by default (use AGENTS.md/CLAUDE.md for root behavior; use --include-root to override)",
+                category: "root",
+            };
+        }
+        return { eligible: true, category: "eligible" };
+    }
+    const polarisEligibility = getPolarisDirectoryEligibility(relPath, opts);
+    if (polarisEligibility) {
+        return polarisEligibility;
+    }
+    // Check against runtime/build artifact patterns (permanently excluded)
+    for (const pattern of exports.RUNTIME_EXCLUDED_DIR_PATTERNS) {
+        // Check if directory name matches exactly
+        if (dirName === pattern) {
+            return {
+                eligible: false,
+                reason: `runtime artifact excluded: ${pattern}`,
+                category: "runtime",
+            };
+        }
+        // Check if any path segment matches
+        if (relPath.includes(`/${pattern}/`) || relPath.startsWith(`${pattern}/`)) {
+            return {
+                eligible: false,
+                reason: `runtime artifact excluded: ${pattern}`,
+                category: "runtime",
+            };
+        }
+    }
+    // Check for agent cognition folders (temporarily excluded, can be opted-in)
+    for (const pattern of exports.AGENT_COGNITION_FOLDERS) {
+        if (dirName === pattern || relPath.includes(`/${pattern}/`) || relPath.startsWith(`${pattern}/`)) {
+            if (opts.includeAgentFolders) {
+                return { eligible: true, category: "eligible" };
+            }
+            return {
+                eligible: false,
+                reason: `agent cognition folder temporarily skipped (use --include-agent-folders to include): ${pattern}`,
+                category: "agent-cognition",
+            };
+        }
+    }
+    // Check for hidden system folders (excluded unless --include-hidden)
+    for (const pattern of exports.HIDDEN_SYSTEM_FOLDERS) {
+        if (dirName === pattern || relPath.includes(`/${pattern}/`) || relPath.startsWith(`${pattern}/`)) {
+            if (opts.includeHidden) {
+                return { eligible: true, category: "eligible" };
+            }
+            return {
+                eligible: false,
+                reason: `hidden system folder (use --include-hidden to include): ${pattern}`,
+                category: "hidden",
+            };
+        }
+    }
+    // Check if path is ignored by .smartdocignore
+    // Note: ignore library requires trailing slash to match directories
+    const ig = parseSmartDocIgnore(repoRoot);
+    if (ig.ignores(relPath) || ig.ignores(`${relPath}/`)) {
+        return {
+            eligible: false,
+            reason: `ignored by .smartdocignore: ${relPath}`,
+            category: "ignored",
+        };
+    }
+    // Other hidden directories (starting with .) are excluded
+    if (dirName.startsWith(".")) {
+        if (opts.includeHidden) {
+            return { eligible: true, category: "eligible" };
+        }
+        return {
+            eligible: false,
+            reason: "hidden directory (use --include-hidden to include)",
+            category: "hidden",
+        };
+    }
+    return { eligible: true, category: "eligible" };
+}

package/dist/smartdocs-engine/smartdoc-ignore.test.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
+function makeRepo() {
+    return (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "polaris-smartdoc-ignore-"));
+}
+(0, vitest_1.describe)("parseSmartDocIgnore", () => {
+    (0, vitest_1.it)("enforces default endpoint artifact patterns when .smartdocignore is absent", () => {
+        const repoRoot = makeRepo();
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.DEFAULT_SMARTDOCIGNORE_PATTERNS).toContain(".taskchain_artifacts/**");
+        (0, vitest_1.expect)((0, smartdoc_ignore_js_1.isIngestIneligible)(".taskchain_artifacts/polaris-run/current-state.json", repoRoot)).toEqual({
+            ineligible: true,
+            reason: "ignored by .smartdocignore/defaults: .taskchain_artifacts/polaris-run/current-state.json",
+        });
+    });
+    (0, vitest_1.it)("enforces all default endpoint artifact families", () => {
+        const repoRoot = makeRepo();
+        for (const path of [
+            "README.md",
+            "AGENTS.md",
+            "CLAUDE.md",
+            "GEMINI.md",
+            "POLARIS.md",
+            ".claude/settings.json",
+            ".codex/AGENTS.md",
+            ".windsurf/rules.md",
+            ".github/workflows/ci.yml",
+            "generated/report.md",
+            "docs/generated/report.md",
+            "summaries/run.md",
+            "docs/summaries/run.md",
+            "smartdocs/docs/specs/active/example.md",
+        ]) {
+            (0, vitest_1.expect)((0, smartdoc_ignore_js_1.isIngestIneligible)(path, repoRoot).ineligible, path).toBe(true);
+        }
+    });
+    (0, vitest_1.it)("parses custom gitignore-style patterns from .smartdocignore", () => {
+        const repoRoot = makeRepo();
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".smartdocignore"), "scratch/**/*.md\n!important.md\n", "utf-8");
+        (0, vitest_1.expect)((0, smartdoc_ignore_js_1.isIngestIneligible)("scratch/plans/test.md", repoRoot).ineligible).toBe(true);
+        (0, vitest_1.expect)((0, smartdoc_ignore_js_1.isIngestIneligible)("important.md", repoRoot).ineligible).toBe(false);
+    });
+    (0, vitest_1.it)("allows non-ignored paths", () => {
+        const repoRoot = makeRepo();
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "smartdocs", "docs", "raw"), { recursive: true });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".smartdocignore"), "tmp/\n", "utf-8");
+        (0, vitest_1.expect)((0, smartdoc_ignore_js_1.isIngestIneligible)("smartdocs/docs/raw/spec.md", repoRoot)).toEqual({ ineligible: false });
+        (0, vitest_1.expect)((0, smartdoc_ignore_js_1.parseSmartDocIgnore)(repoRoot).ignores("smartdocs/docs/raw/spec.md")).toBe(false);
+    });
+});
+(0, vitest_1.describe)("isDirectoryEligible", () => {
+    (0, vitest_1.it)("marks build artifact directories as ineligible", () => {
+        const repoRoot = makeRepo();
+        for (const dir of ["node_modules", "dist", "build", "coverage"]) {
+            const fullPath = (0, node_path_1.join)(repoRoot, dir);
+            (0, node_fs_1.mkdirSync)(fullPath, { recursive: true });
+            const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)(fullPath, repoRoot);
+            (0, vitest_1.expect)(result.eligible, dir).toBe(false);
+            (0, vitest_1.expect)(result.reason, dir).toContain("runtime artifact excluded");
+            (0, vitest_1.expect)(result.category, dir).toBe("runtime");
+        }
+    });
+    (0, vitest_1.it)("marks runtime and system hidden directories as ineligible", () => {
+        const repoRoot = makeRepo();
+        for (const dir of [".git", ".polaris", ".github", ".windsurf"]) {
+            const fullPath = (0, node_path_1.join)(repoRoot, dir);
+            (0, node_fs_1.mkdirSync)(fullPath, { recursive: true });
+            const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)(fullPath, repoRoot);
+            (0, vitest_1.expect)(result.eligible, dir).toBe(false);
+            (0, vitest_1.expect)(result.category, dir).toMatch(/runtime|hidden/);
+        }
+    });
+    (0, vitest_1.it)("marks nested ineligible directories as ineligible", () => {
+        const repoRoot = makeRepo();
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "src", "node_modules"), { recursive: true });
+        const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)((0, node_path_1.join)(repoRoot, "src", "node_modules"), repoRoot);
+        (0, vitest_1.expect)(result.eligible).toBe(false);
+        (0, vitest_1.expect)(result.reason).toContain("runtime artifact excluded: node_modules");
+        (0, vitest_1.expect)(result.category).toBe("runtime");
+    });
+    (0, vitest_1.it)("marks directories ignored by .smartdocignore as ineligible", () => {
+        const repoRoot = makeRepo();
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "custom-ignore"), { recursive: true });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".smartdocignore"), "custom-ignore/\n", "utf-8");
+        const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)((0, node_path_1.join)(repoRoot, "custom-ignore"), repoRoot);
+        (0, vitest_1.expect)(result.eligible).toBe(false);
+        (0, vitest_1.expect)(result.reason).toContain("ignored by .smartdocignore");
+    });
+    (0, vitest_1.it)("marks eligible source directories as eligible", () => {
+        const repoRoot = makeRepo();
+        for (const dir of ["src", "docs", "lib", "packages", "core"]) {
+            const fullPath = (0, node_path_1.join)(repoRoot, dir);
+            (0, node_fs_1.mkdirSync)(fullPath, { recursive: true });
+            const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)(fullPath, repoRoot);
+            (0, vitest_1.expect)(result.eligible, dir).toBe(true);
+        }
+    });
+    (0, vitest_1.it)("includes all expected runtime excluded patterns", () => {
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).toContain("node_modules");
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).toContain("dist");
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).toContain("build");
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).toContain("coverage");
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).toContain(".git");
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).toContain(".polaris");
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).toContain("generated");
+        (0, vitest_1.expect)(smartdoc_ignore_js_1.RUNTIME_EXCLUDED_DIR_PATTERNS).not.toContain("smartdocs"); // smartdocs/ protected via targeted DEFAULT_SMARTDOCIGNORE_PATTERNS
+    });
+    (0, vitest_1.it)("marks agent cognition folders as temporarily skipped with agent-cognition category", () => {
+        const repoRoot = makeRepo();
+        for (const dir of smartdoc_ignore_js_1.AGENT_COGNITION_FOLDERS) {
+            const fullPath = (0, node_path_1.join)(repoRoot, dir);
+            (0, node_fs_1.mkdirSync)(fullPath, { recursive: true });
+            const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)(fullPath, repoRoot);
+            (0, vitest_1.expect)(result.eligible, dir).toBe(false);
+            (0, vitest_1.expect)(result.category, dir).toBe("agent-cognition");
+            (0, vitest_1.expect)(result.reason, dir).toContain("agent cognition folder temporarily skipped");
+        }
+    });
+    (0, vitest_1.it)("allows agent cognition folders with includeAgentFolders option", () => {
+        const repoRoot = makeRepo();
+        for (const dir of smartdoc_ignore_js_1.AGENT_COGNITION_FOLDERS) {
+            const fullPath = (0, node_path_1.join)(repoRoot, dir);
+            (0, node_fs_1.mkdirSync)(fullPath, { recursive: true });
+            const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)(fullPath, repoRoot, { includeAgentFolders: true });
+            (0, vitest_1.expect)(result.eligible, dir).toBe(true);
+            (0, vitest_1.expect)(result.category, dir).toBe("eligible");
+        }
+    });
+    (0, vitest_1.it)("marks root as skipped by default with root category", () => {
+        const repoRoot = makeRepo();
+        const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)(repoRoot, repoRoot, { isRoot: true });
+        (0, vitest_1.expect)(result.eligible).toBe(false);
+        (0, vitest_1.expect)(result.category).toBe("root");
+        (0, vitest_1.expect)(result.reason).toContain("root skipped by default");
+    });
+    (0, vitest_1.it)("allows root with skipRoot: false option", () => {
+        const repoRoot = makeRepo();
+        const result = (0, smartdoc_ignore_js_1.isDirectoryEligible)(repoRoot, repoRoot, { isRoot: true, skipRoot: false });
+        (0, vitest_1.expect)(result.eligible).toBe(true);
+        (0, vitest_1.expect)(result.category).toBe("eligible");
+    });
+});