@lsctech/polaris 0.1.0

package/dist/smartdocs-engine/migrate.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAllowedException = isAllowedException;
+exports.migrateDocs = migrateDocs;
+exports.printMigrateResults = printMigrateResults;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
+/** Basenames that are always allowed regardless of location. */
+const ALLOWED_BASENAMES = new Set([
+    "README.md",
+    "POLARIS.md",
+    "CHANGELOG.md",
+    "LICENSE.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    "COPILOT.md",
+]);
+/**
+ * Directory prefixes (relative to repo root, forward-slash notation) where
+ * markdown files may live without being migrated.
+ */
+const ALLOWED_DIR_PREFIXES = [
+    ".agents/",
+    ".codex/",
+    ".claude/",
+    ".gemini/",
+    ".github/",
+    ".polaris/",
+    ".taskchain_artifacts/",
+    "generated/",
+    "summaries/",
+    "smartdocs/",
+];
+function isAllowedException(relPath, repoRoot) {
+    const name = (0, node_path_1.basename)(relPath);
+    if (ALLOWED_BASENAMES.has(name)) {
+        return { allowed: true, reason: `allowed basename: ${name}` };
+    }
+    for (const prefix of ALLOWED_DIR_PREFIXES) {
+        if (relPath.startsWith(prefix)) {
+            return { allowed: true, reason: `in allowed directory: ${prefix}` };
+        }
+    }
+    if (repoRoot) {
+        const eligibility = (0, smartdoc_ignore_js_1.isIngestIneligible)(relPath, repoRoot);
+        if (eligibility.ineligible) {
+            return {
+                allowed: true,
+                reason: eligibility.reason,
+                endpointArtifactReason: "smartdocignore-endpoint-artifact",
+            };
+        }
+    }
+    return { allowed: false };
+}
+function findMarkdownFiles(repoRoot) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["ls-files", "--cached", "--others", "--exclude-standard", "*.md"], { cwd: repoRoot, encoding: "utf-8" });
+        return output
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0 && l.endsWith(".md"));
+    }
+    catch {
+        // Fallback if not a git repo: use find
+        const output = (0, node_child_process_1.execFileSync)("find", [".", "-name", "*.md", "-not", "-path", "./.git/*"], { cwd: repoRoot, encoding: "utf-8" });
+        return output
+            .split("\n")
+            .map((l) => l.trim().replace(/^\.\//, ""))
+            .filter((l) => l.length > 0 && l.endsWith(".md"));
+    }
+}
+function uniqueDestination(filePath) {
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return filePath;
+    const dir = (0, node_path_1.dirname)(filePath);
+    const name = (0, node_path_1.basename)(filePath, ".md");
+    let index = 2;
+    let candidate = (0, node_path_1.join)(dir, `${name}-${index}.md`);
+    while ((0, node_fs_1.existsSync)(candidate)) {
+        index += 1;
+        candidate = (0, node_path_1.join)(dir, `${name}-${index}.md`);
+    }
+    return candidate;
+}
+function makeMigrationRunId() {
+    const date = new Date().toISOString().slice(0, 10);
+    const seq = String(Date.now()).slice(-4);
+    return `polaris-docs-migrate-${date}-${seq}`;
+}
+function batchFiles(files, batchSize = 4) {
+    const batches = [];
+    for (let i = 0; i < files.length; i += batchSize) {
+        batches.push(files.slice(i, i + batchSize));
+    }
+    return batches;
+}
+/**
+ * Migrates markdown files in a repository into smartdocs/raw/, records provenance for moved files, and summarizes the migration.
+ *
+ * @param options - Migration options including the repository root, an optional dry-run flag, and an optional migration run identifier.
+ *   - `repoRoot`: Path to the repository root containing markdown files to evaluate and migrate.
+ *   - `dryRun`: When true, no files are moved or written; results describe what would have happened.
+ *   - `migrationRunId`: If provided, use this identifier for provenance records; otherwise a new id is generated.
+ * @returns An object summarizing the migration:
+ *   - `results`: Per-file results showing original path, current path, classification (`"allowed-exception"` or `"migrated"`), and optional fields such as `exceptionReason`, `endpointArtifactReason`, or `destination`.
+ *   - `migrationRunId`: The migration run identifier used for this operation.
+ *   - `provenancePath`: Relative path to the written provenance JSON file when not a dry run and provenance was recorded; `null` otherwise.
+ *   - `ingestBatches`: Array of batches (arrays) of destination paths suitable for ingestion.
+ *   - `dryRun`: Boolean reflecting whether the operation was a dry run.
+ */
+function migrateDocs(options) {
+    const repoRoot = (0, node_path_1.resolve)(options.repoRoot);
+    const migrationRunId = options.migrationRunId ?? makeMigrationRunId();
+    const rawDir = (0, node_path_1.resolve)(repoRoot, "smartdocs/raw");
+    const allMd = findMarkdownFiles(repoRoot);
+    const results = [];
+    const toMigrate = [];
+    for (const relPath of allMd) {
+        const check = isAllowedException(relPath, repoRoot);
+        if (check.allowed) {
+            results.push({
+                originalPath: relPath,
+                currentPath: relPath,
+                classification: "allowed-exception",
+                exceptionReason: check.reason,
+                endpointArtifactReason: check.endpointArtifactReason,
+            });
+        }
+        else {
+            toMigrate.push(relPath);
+        }
+    }
+    if (!options.dryRun && toMigrate.length > 0) {
+        (0, node_fs_1.mkdirSync)(rawDir, { recursive: true });
+    }
+    const provenanceRecords = [];
+    for (const relPath of toMigrate) {
+        const absSource = (0, node_path_1.resolve)(repoRoot, relPath);
+        const destFile = uniqueDestination((0, node_path_1.join)(rawDir, (0, node_path_1.basename)(relPath)));
+        const relDest = (0, node_path_1.relative)(repoRoot, destFile).replace(/\\/g, "/");
+        if (!options.dryRun) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(destFile), { recursive: true });
+            (0, node_fs_1.renameSync)(absSource, destFile);
+            provenanceRecords.push({
+                originalPath: relPath,
+                currentPath: relDest,
+                migratedAt: new Date().toISOString(),
+                migrationRunId,
+            });
+        }
+        results.push({
+            originalPath: relPath,
+            currentPath: options.dryRun ? relPath : relDest,
+            classification: "migrated",
+            destination: relDest,
+        });
+    }
+    let provenancePath = null;
+    if (!options.dryRun && provenanceRecords.length > 0) {
+        const provDir = (0, node_path_1.resolve)(repoRoot, ".taskchain_artifacts", "polaris-docs-migrate", migrationRunId);
+        (0, node_fs_1.mkdirSync)(provDir, { recursive: true });
+        const absProvPath = (0, node_path_1.join)(provDir, "provenance.json");
+        (0, node_fs_1.writeFileSync)(absProvPath, JSON.stringify(provenanceRecords, null, 2) + "\n", "utf-8");
+        provenancePath = (0, node_path_1.relative)(repoRoot, absProvPath).replace(/\\/g, "/");
+    }
+    // Build ingest batch paths: where files will land in smartdocs/raw/
+    const migratedDestPaths = results
+        .filter((r) => r.classification === "migrated")
+        .map((r) => r.destination ?? `smartdocs/raw/${(0, node_path_1.basename)(r.originalPath)}`);
+    const ingestBatches = batchFiles(migratedDestPaths, 4);
+    return { results, migrationRunId, provenancePath, ingestBatches, dryRun: Boolean(options.dryRun) };
+}
+/**
+ * Prints a human-readable summary of a migration run to stdout.
+ *
+ * The summary includes the migration run ID, number of files to migrate, each migrated
+ * file and its destination (or the default `raw/<basename>`), allowed exceptions with
+ * their reasons, ingest batches rendered as `polaris docs ingest --file <path>` commands,
+ * and the provenance file path when present. A "[dry-run] " prefix is added when `result.dryRun`
+ * is true.
+ *
+ * @param result - The migration result object containing per-file classifications, ingest batches,
+ *                 provenance path, and the `dryRun` flag
+ */
+function printMigrateResults(result) {
+    const prefix = result.dryRun ? "[dry-run] " : "";
+    const migrated = result.results.filter((r) => r.classification === "migrated");
+    const exceptions = result.results.filter((r) => r.classification === "allowed-exception");
+    console.log(`\n${prefix}Migration run: ${result.migrationRunId}`);
+    console.log(`${prefix}Files to migrate: ${migrated.length}`);
+    for (const r of migrated) {
+        const dest = r.destination ?? `raw/${(0, node_path_1.basename)(r.originalPath)}`;
+        console.log(`  ${r.originalPath} -> ${dest}`);
+    }
+    if (exceptions.length > 0) {
+        console.log(`\n${prefix}Allowed exceptions (not moved): ${exceptions.length}`);
+        for (const r of exceptions) {
+            console.log(`  ${r.originalPath}  [${r.exceptionReason}]`);
+        }
+    }
+    if (result.ingestBatches.length > 0) {
+        console.log(`\n${prefix}Ingest cluster batches (${result.ingestBatches.length} batch${result.ingestBatches.length === 1 ? "" : "es"}):`);
+        result.ingestBatches.forEach((batch, i) => {
+            console.log(`  Batch ${i + 1}:`);
+            for (const f of batch) {
+                console.log(`    polaris docs ingest --file ${f}`);
+            }
+        });
+    }
+    if (result.provenancePath) {
+        console.log(`\nProvenance written to: ${result.provenancePath}`);
+    }
+}

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

@@ -0,0 +1,200 @@
+"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_fs_2 = require("node:fs");
+const node_os_1 = require("node:os");
+const vitest_1 = require("vitest");
+const migrate_js_1 = require("./migrate.js");
+// ---------------------------------------------------------------------------
+// isAllowedException
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("isAllowedException", () => {
+    (0, vitest_1.it)("allows README.md in any directory", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("README.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/README.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("some/deep/path/README.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows POLARIS.md in any directory", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("POLARIS.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/cli/POLARIS.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows CHANGELOG.md and LICENSE.md", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("CHANGELOG.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("LICENSE.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("does NOT allow arbitrary docs/ files (docs/ is a migration source, not an exception)", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("docs/spec/foo.md").allowed).toBe(false);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("docs/raw/bar.md").allowed).toBe(false);
+    });
+    (0, vitest_1.it)("allows anything under .agents/, .codex/, .claude/, .taskchain_artifacts/", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".agents/instructions.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".codex/skills/foo/SKILL.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".claude/CLAUDE.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".taskchain_artifacts/run/notes.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows anything under .polaris/skills/, .gemini/, .github/skills/", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".polaris/skills/polaris-run/SKILL.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".gemini/skills/polaris-run/SKILL.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".github/skills/polaris-run/SKILL.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("does NOT allow arbitrary markdown files", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/some-feature/NOTES.md").allowed).toBe(false);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("planning/ideas.md").allowed).toBe(false);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("scratch.md").allowed).toBe(false);
+    });
+    (0, vitest_1.it)("allows AGENTS.md, CLAUDE.md, GEMINI.md, COPILOT.md in any directory", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("AGENTS.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/AGENTS.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("CLAUDE.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/CLAUDE.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("GEMINI.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/GEMINI.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("COPILOT.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows files in smartdocs/, generated/, summaries/", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("smartdocs/some-doc.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("generated/output.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("summaries/summary.md").allowed).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// migrateDocs — dry-run
+// ---------------------------------------------------------------------------
+function makeGitRepo() {
+    const repoRoot = (0, node_fs_2.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "polaris-migrate-"));
+    (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 absPath = (0, node_path_1.join)(repoRoot, relPath);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, relPath.split("/").slice(0, -1).join("/")), { recursive: true });
+    (0, node_fs_1.writeFileSync)(absPath, content, "utf-8");
+    (0, node_child_process_1.execFileSync)("git", ["add", relPath], { cwd: repoRoot });
+}
+(0, vitest_1.describe)("migrateDocs --dry-run", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeGitRepo();
+    });
+    (0, vitest_1.it)("reports files to migrate and allowed exceptions, does not move files", () => {
+        addTrackedFile(repoRoot, "README.md");
+        addTrackedFile(repoRoot, "planning/ideas.md");
+        addTrackedFile(repoRoot, "docs/spec/existing.md");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: true, migrationRunId: "test-migrate-001" });
+        (0, vitest_1.expect)(result.dryRun).toBe(true);
+        (0, vitest_1.expect)(result.migrationRunId).toBe("test-migrate-001");
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        const exceptions = result.results.filter((r) => r.classification === "allowed-exception");
+        (0, vitest_1.expect)(migrated).toHaveLength(2);
+        const migratedPaths = migrated.map((r) => r.originalPath);
+        (0, vitest_1.expect)(migratedPaths).toContain("planning/ideas.md");
+        (0, vitest_1.expect)(migratedPaths).toContain("docs/spec/existing.md");
+        (0, vitest_1.expect)(exceptions.length).toBeGreaterThanOrEqual(1);
+        // Files must NOT have been moved
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "planning/ideas.md"))).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "smartdocs/docs/raw/ideas.md"))).toBe(false);
+        // No provenance written in dry-run
+        (0, vitest_1.expect)(result.provenancePath).toBeNull();
+    });
+    (0, vitest_1.it)("produces ingest batches of at most 4 files", () => {
+        for (let i = 0; i < 9; i++) {
+            addTrackedFile(repoRoot, `planning/doc${i}.md`);
+        }
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: true, migrationRunId: "test-migrate-002" });
+        const allBatched = result.ingestBatches.flat();
+        (0, vitest_1.expect)(allBatched).toHaveLength(9);
+        for (const batch of result.ingestBatches) {
+            (0, vitest_1.expect)(batch.length).toBeLessThanOrEqual(4);
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// migrateDocs — actual migration
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("migrateDocs (live)", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeGitRepo();
+    });
+    (0, vitest_1.it)("moves files to smartdocs/docs/raw/, writes provenance JSON", () => {
+        addTrackedFile(repoRoot, "README.md");
+        addTrackedFile(repoRoot, "scratch/notes.md", "# Notes");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: false, migrationRunId: "test-migrate-live-001" });
+        (0, vitest_1.expect)(result.dryRun).toBe(false);
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].originalPath).toBe("scratch/notes.md");
+        (0, vitest_1.expect)(migrated[0].currentPath).toBe("smartdocs/docs/raw/notes.md");
+        // File should now exist in smartdocs/docs/raw/
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "smartdocs/docs/raw/notes.md"))).toBe(true);
+        // File should no longer exist at original location
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "scratch/notes.md"))).toBe(false);
+        // Provenance written
+        (0, vitest_1.expect)(result.provenancePath).not.toBeNull();
+        const provContent = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, result.provenancePath), "utf-8"));
+        (0, vitest_1.expect)(provContent).toHaveLength(1);
+        (0, vitest_1.expect)(provContent[0].originalPath).toBe("scratch/notes.md");
+        (0, vitest_1.expect)(provContent[0].currentPath).toBe("smartdocs/docs/raw/notes.md");
+        (0, vitest_1.expect)(provContent[0].migrationRunId).toBe("test-migrate-live-001");
+        (0, vitest_1.expect)(provContent[0].migratedAt).toBeTruthy();
+    });
+    (0, vitest_1.it)("excludes AGENTS.md, CLAUDE.md, GEMINI.md from migration queue by default", () => {
+        addTrackedFile(repoRoot, "AGENTS.md", "# Agents");
+        addTrackedFile(repoRoot, "CLAUDE.md", "# Claude");
+        addTrackedFile(repoRoot, "GEMINI.md", "# Gemini");
+        addTrackedFile(repoRoot, "scratch/notes.md", "# Notes");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: true, migrationRunId: "test-endpoint-001" });
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        const exceptions = result.results.filter((r) => r.classification === "allowed-exception");
+        // Only scratch/notes.md should be migrated
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].originalPath).toBe("scratch/notes.md");
+        // AGENTS.md, CLAUDE.md, GEMINI.md should be exceptions
+        const exceptionPaths = exceptions.map((r) => r.originalPath);
+        (0, vitest_1.expect)(exceptionPaths).toContain("AGENTS.md");
+        (0, vitest_1.expect)(exceptionPaths).toContain("CLAUDE.md");
+        (0, vitest_1.expect)(exceptionPaths).toContain("GEMINI.md");
+    });
+    (0, vitest_1.it)("does not re-migrate files in smartdocs/", () => {
+        addTrackedFile(repoRoot, "smartdocs/smart-doc.md", "# Smart Doc");
+        addTrackedFile(repoRoot, "scratch/notes.md", "# Notes");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: true, migrationRunId: "test-endpoint-002" });
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        const exceptions = result.results.filter((r) => r.classification === "allowed-exception");
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].originalPath).toBe("scratch/notes.md");
+        const exceptionPaths = exceptions.map((r) => r.originalPath);
+        (0, vitest_1.expect)(exceptionPaths).toContain("smartdocs/smart-doc.md");
+    });
+    (0, vitest_1.it)("respects .smartdocignore custom patterns in migrate", () => {
+        // Write a .smartdocignore with a custom pattern
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".smartdocignore"), "custom-ignore/**\n", "utf-8");
+        (0, node_child_process_1.execFileSync)("git", ["add", ".smartdocignore"], { cwd: repoRoot });
+        addTrackedFile(repoRoot, "custom-ignore/secret.md", "# Secret");
+        addTrackedFile(repoRoot, "scratch/notes.md", "# Notes");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: true, migrationRunId: "test-endpoint-003" });
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        const exceptions = result.results.filter((r) => r.classification === "allowed-exception");
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].originalPath).toBe("scratch/notes.md");
+        const smartdocExceptions = exceptions.filter((r) => r.endpointArtifactReason === "smartdocignore-endpoint-artifact");
+        (0, vitest_1.expect)(smartdocExceptions.length).toBeGreaterThanOrEqual(1);
+        const ignoredPaths = smartdocExceptions.map((r) => r.originalPath);
+        (0, vitest_1.expect)(ignoredPaths).toContain("custom-ignore/secret.md");
+    });
+    (0, vitest_1.it)("handles filename collisions by uniquifying destination", () => {
+        (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, "smartdocs/docs/raw/notes.md"), "# Existing", "utf-8");
+        (0, node_child_process_1.execFileSync)("git", ["add", "smartdocs/docs/raw/notes.md"], { cwd: repoRoot });
+        addTrackedFile(repoRoot, "scratch/notes.md", "# Incoming");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: false, migrationRunId: "test-migrate-live-002" });
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].currentPath).toBe("smartdocs/docs/raw/notes-2.md");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "smartdocs/docs/raw/notes-2.md"))).toBe(true);
+    });
+});