@lsctech/polaris 0.1.0

package/dist/map/backfill.test.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const backfill_js_1 = require("./backfill.js");
+const TMP = (0, node_path_1.join)(process.cwd(), ".test-backfill-tmp");
+const EXISTING_ROUTES = {
+    "src/cli/index.ts": {
+        domain: "cli",
+        route: "src/cli",
+        taskchain: "polaris-cli",
+        confidence: 0.95,
+        classification: "indexed",
+        last_updated: "2026-05-22T20:00:00Z",
+        updated_by: "polaris-map-index",
+        tags: ["cli", "entry-point"],
+    },
+};
+const POLARIS_CONFIG = {
+    repo: { sourceRoots: ["src"], docsRoots: [], sidecarOutputPath: ".polaris/map" },
+    map: { autoWriteAbove: 0.85, confidenceThreshold: 0.75 },
+};
+function setup() {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, ".polaris/map"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "src/cli"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "src/map"), { recursive: true });
+    // Pre-existing file already in atlas
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/cli/index.ts"), "");
+    // New unmapped file — should be backfilled
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/cli/version.ts"), "");
+    // New file in a different domain
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/backfill.ts"), "");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), JSON.stringify(EXISTING_ROUTES));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/needs-review.json"), JSON.stringify({}));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/exemptions.json"), JSON.stringify({}));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/index.json"), JSON.stringify({ scan_date: "", file_count: 0, coverage_pct: 0, entries: {} }));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "polaris.config.json"), JSON.stringify(POLARIS_CONFIG));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polarisignore"), "*.log\n");
+}
+function teardown() {
+    (0, node_fs_1.rmSync)(TMP, { recursive: true, force: true });
+}
+function captureOutput(fn) {
+    const stdoutLines = [];
+    const stderrLines = [];
+    const origLog = console.log.bind(console);
+    const origError = console.error.bind(console);
+    const origStdout = process.stdout.write.bind(process.stdout);
+    const origStderr = process.stderr.write.bind(process.stderr);
+    console.log = (...args) => { stdoutLines.push(args.map(String).join(" ")); };
+    console.error = (...args) => { stderrLines.push(args.map(String).join(" ")); };
+    process.stdout.write = (chunk) => { stdoutLines.push(String(chunk)); return true; };
+    process.stderr.write = (chunk) => { stderrLines.push(String(chunk)); return true; };
+    try {
+        fn();
+    }
+    finally {
+        console.log = origLog;
+        console.error = origError;
+        process.stdout.write = origStdout;
+        process.stderr.write = origStderr;
+    }
+    return { stdout: stdoutLines.join(""), stderr: stderrLines.join("") };
+}
+(0, vitest_1.describe)("runMapBackfill", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("adds unmapped files to file-routes.json without touching existing entries", () => {
+        captureOutput(() => (0, backfill_js_1.runMapBackfill)(TMP, false, undefined, false));
+        const routes = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), "utf-8"));
+        // Existing entry preserved
+        (0, vitest_1.expect)(routes["src/cli/index.ts"].confidence).toBe(0.95);
+        (0, vitest_1.expect)(routes["src/cli/index.ts"].updated_by).toBe("polaris-map-index");
+        // New entry added
+        (0, vitest_1.expect)(routes["src/cli/version.ts"] || routes["src/map/backfill.ts"]).toBeTruthy();
+    });
+    (0, vitest_1.it)("reports correct summary counts", () => {
+        const { stdout } = captureOutput(() => (0, backfill_js_1.runMapBackfill)(TMP, false, undefined, false));
+        (0, vitest_1.expect)(stdout).toMatch(/Backfilled \d+ files\. Added \d+\. Queued \d+ for review\. Skipped \d+/);
+        // src/cli/index.ts should be counted as skipped
+        (0, vitest_1.expect)(stdout).toContain("Skipped 1");
+    });
+    (0, vitest_1.it)("does not write files when --dry-run is set", () => {
+        const beforeRoutes = (0, node_fs_1.readFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), "utf-8");
+        const { stdout } = captureOutput(() => (0, backfill_js_1.runMapBackfill)(TMP, true, undefined, false));
+        const afterRoutes = (0, node_fs_1.readFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), "utf-8");
+        (0, vitest_1.expect)(afterRoutes).toBe(beforeRoutes);
+        (0, vitest_1.expect)(stdout).toContain("dry-run");
+    });
+    (0, vitest_1.it)("limits backfill to --domain when specified", () => {
+        captureOutput(() => (0, backfill_js_1.runMapBackfill)(TMP, false, "cli", false));
+        const routes = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), "utf-8"));
+        // cli domain file added
+        (0, vitest_1.expect)(routes["src/cli/version.ts"]).toBeTruthy();
+        // map domain file NOT added (filtered out)
+        (0, vitest_1.expect)(routes["src/map/backfill.ts"]).toBeUndefined();
+    });
+    (0, vitest_1.it)("never overwrites an existing entry in a second run", () => {
+        captureOutput(() => (0, backfill_js_1.runMapBackfill)(TMP, false, undefined, false));
+        const routesAfterFirst = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), "utf-8"));
+        const versionEntry = routesAfterFirst["src/cli/version.ts"];
+        captureOutput(() => (0, backfill_js_1.runMapBackfill)(TMP, false, undefined, false));
+        const routesAfterSecond = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), "utf-8"));
+        (0, vitest_1.expect)(routesAfterSecond["src/cli/version.ts"]).toEqual(versionEntry);
+    });
+    (0, vitest_1.it)("errors if atlas is not initialized", () => {
+        (0, node_fs_1.rmSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"));
+        let exited = false;
+        const origExit = process.exit.bind(process);
+        process.exit = (() => { exited = true; });
+        try {
+            captureOutput(() => (0, backfill_js_1.runMapBackfill)(TMP, false, undefined, false));
+        }
+        finally {
+            process.exit = origExit;
+        }
+        (0, vitest_1.expect)(exited).toBe(true);
+    });
+});

package/dist/map/index.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMapIndex = runMapIndex;
+exports.createMapCommand = createMapCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const commander_1 = require("commander");
+const loader_js_1 = require("../config/loader.js");
+const update_js_1 = require("./update.js");
+const validate_js_1 = require("./validate.js");
+const query_js_1 = require("./query.js");
+const backfill_js_1 = require("./backfill.js");
+const welfare_js_1 = require("./welfare.js");
+const parser_js_1 = require("../ignore/parser.js");
+const defaults_js_1 = require("../ignore/defaults.js");
+const inference_js_1 = require("./inference.js");
+const atlas_js_1 = require("./atlas.js");
+const SECRET_REGEXES = defaults_js_1.SECRET_PATTERNS.map((p) => new RegExp("^" + p.replace(/\./g, "\\.").replace(/\*/g, ".*") + "$"));
+function isSecretFile(filePath) {
+    const parts = filePath.split("/");
+    const base = parts[parts.length - 1];
+    return SECRET_REGEXES.some((re) => re.test(base) || re.test(filePath));
+}
+function* walkDir(dir, root, ig) {
+    for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+        const full = (0, node_path_1.join)(dir, entry.name);
+        const rel = (0, node_path_1.relative)(root, full).replace(/\\/g, "/");
+        if (entry.isDirectory()) {
+            if (ig?.ignores(rel + "/"))
+                continue;
+            yield* walkDir(full, root, ig);
+        }
+        else {
+            yield rel;
+        }
+    }
+}
+function getBranchName(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: repoRoot,
+            stdio: ["pipe", "pipe", "pipe"],
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return "";
+    }
+}
+function loadIgnoreFilter(repoRoot) {
+    let userPatterns = [];
+    try {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(repoRoot, ".polarisignore"), "utf-8");
+        userPatterns = raw.split(/\r?\n/).filter((line) => line.trim() !== "" && !line.startsWith("#"));
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && "code" in err && err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    return (0, parser_js_1.parsePolarisIgnore)(userPatterns);
+}
+function runMapIndex(repoRoot, dryRun, verbose, _options = {}) {
+    if (!(0, node_fs_1.existsSync)(repoRoot)) {
+        console.error(`Repo root not found: ${repoRoot}`);
+        process.exit(1);
+    }
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const outputPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const branchName = getBranchName(repoRoot);
+    const ig = loadIgnoreFilter(repoRoot);
+    const existingRoutes = (0, atlas_js_1.readFileRoutes)(outputPath);
+    const existingExemptions = (0, atlas_js_1.readExemptions)(outputPath);
+    const newRoutes = {};
+    const newNeedsReview = {};
+    const newExemptions = { ...existingExemptions };
+    let scanned = 0;
+    let mapped = 0;
+    let trackedNotIndexed = 0;
+    let needsReview = 0;
+    let ignored = 0;
+    const now = new Date().toISOString();
+    for (const filePath of walkDir(repoRoot, repoRoot, ig)) {
+        scanned++;
+        // Security check — never process secret files
+        if (isSecretFile(filePath)) {
+            console.error(`[HIGH] Secret file pattern matched, skipping: ${filePath}`);
+            ignored++;
+            continue;
+        }
+        // 1. .polarisignore
+        if (ig.ignores(filePath)) {
+            ignored++;
+            if (verbose)
+                console.log(`  ignored: ${filePath}`);
+            continue;
+        }
+        // 2. exemptions.json
+        if (existingExemptions[filePath]) {
+            trackedNotIndexed++;
+            if (verbose)
+                console.log(`  tracked-not-indexed (exemption): ${filePath}`);
+            continue;
+        }
+        // 3. generatedRoots
+        const isGenerated = (config.repo.generatedRoots ?? []).some((root) => {
+            const prefix = root.endsWith("/") ? root : `${root}/`;
+            return filePath.startsWith(prefix);
+        });
+        if (isGenerated) {
+            newExemptions[filePath] = { classification: "tracked-not-indexed", reason: "generatedRoots" };
+            trackedNotIndexed++;
+            if (verbose)
+                console.log(`  tracked-not-indexed (generated): ${filePath}`);
+            continue;
+        }
+        // 4. Route inference
+        const inferred = (0, inference_js_1.inferRoute)(filePath, repoRoot, config, existingRoutes, branchName);
+        const entry = {
+            domain: inferred.domain,
+            route: inferred.route,
+            taskchain: inferred.taskchain,
+            confidence: inferred.confidence,
+            classification: inferred.confidence >= (config.map.autoWriteAbove ?? 0.85) ? "indexed" : "needs-review",
+            last_updated: now,
+            updated_by: "polaris-map-index",
+            tags: inferred.tags,
+            instructionFile: (0, atlas_js_1.resolveInstructionFile)(filePath, repoRoot),
+        };
+        if (inferred.confidence >= (config.map.autoWriteAbove ?? 0.85)) {
+            newRoutes[filePath] = entry;
+            mapped++;
+            if (verbose)
+                console.log(`  indexed (${inferred.confidence.toFixed(2)}): ${filePath}`);
+        }
+        else {
+            newNeedsReview[filePath] = entry;
+            needsReview++;
+            if (verbose)
+                console.log(`  needs-review (${inferred.confidence.toFixed(2)}): ${filePath}`);
+        }
+    }
+    const coveragePct = scanned > 0 ? Math.round((mapped / scanned) * 100) : 0;
+    if (!dryRun) {
+        (0, atlas_js_1.writeFileRoutes)(outputPath, newRoutes);
+        (0, atlas_js_1.writeNeedsReview)(outputPath, newNeedsReview);
+        (0, atlas_js_1.writeExemptions)(outputPath, newExemptions);
+        const allEntries = { ...newRoutes, ...newNeedsReview };
+        (0, atlas_js_1.writeAtlasIndex)(outputPath, {
+            scan_date: now,
+            file_count: scanned,
+            coverage_pct: coveragePct,
+            instructionCoverage: (0, atlas_js_1.computeInstructionCoverage)(allEntries),
+            entries: allEntries,
+        });
+    }
+    console.log(`Scanned ${scanned} files. Mapped ${mapped}. Tracked-not-indexed ${trackedNotIndexed}. Needs-review ${needsReview}. Ignored ${ignored}.`);
+    if (dryRun)
+        console.log("(dry-run: no files written)");
+}
+function failMissingSubcommand(command, commandName) {
+    const unknownSubcommand = command.args[0];
+    const message = unknownSubcommand
+        ? `error: unknown command '${unknownSubcommand}' for '${commandName}'. Run '${commandName} --help'.`
+        : `error: missing command for '${commandName}'. Run '${commandName} --help'.`;
+    command.error(message, {
+        code: "commander.missingCommand",
+        exitCode: 1,
+    });
+}
+function createMapCommand(handlers = {}) {
+    const indexHandler = handlers.runMapIndex ?? runMapIndex;
+    const updateHandler = handlers.runMapUpdate ?? update_js_1.runMapUpdate;
+    const validateHandler = handlers.runMapValidate ?? validate_js_1.runMapValidate;
+    const backfillHandler = handlers.runMapBackfill ?? backfill_js_1.runMapBackfill;
+    const queryHandler = handlers.runMapQuery ?? query_js_1.runMapQuery;
+    const repoRootDefault = handlers.repoRoot ?? process.cwd();
+    const map = new commander_1.Command("map")
+        .description("Polaris atlas map commands: --dry-run is a non-mutating preview")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    map.action(() => failMissingSubcommand(map, "polaris map"));
+    map
+        .command("index")
+        .description("mutating: full first-pass atlas generation")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--dry-run", "non-mutating preview: print results without writing files")
+        .option("-v, --verbose", "Show per-file classification")
+        .action((options) => {
+        indexHandler(options.repoRoot, options.dryRun ?? false, options.verbose ?? false);
+    });
+    map
+        .command("update")
+        .description("mutating: incremental changed-file mapping")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--changed [files...]", "Changed files (omit to detect from git diff)")
+        .option("--from-commit <sha>", "Start commit for diff (default: HEAD~1)")
+        .option("--to-commit <sha>", "End commit for diff (default: HEAD)")
+        .option("--seed-cognition", "Create draft POLARIS.md and SUMMARY.md for newly eligible folders (default: report only)")
+        .option("--include-root", "Include root folder in cognition surface detection/seeding (skipped by default)")
+        .action((options) => {
+        const files = Array.isArray(options.changed) ? options.changed : [];
+        const { hasNeedsReview } = updateHandler(options.repoRoot, files, options.fromCommit, options.toCommit, options.seedCognition, options.includeRoot);
+        const onLowConfidence = (0, loader_js_1.loadConfig)(options.repoRoot).map.onLowConfidence ?? "warn";
+        if (hasNeedsReview && onLowConfidence === "fail")
+            process.exit(1);
+    });
+    map
+        .command("validate")
+        .description("safe/read-only by default: atlas integrity check and needs-review reporting")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--stale-threshold <days>", "Days before an entry is considered stale", "30")
+        .option("--fix <path>", "Show and optionally fix entry for a specific file")
+        .action((options) => {
+        const { hasError } = validateHandler(options.repoRoot, parseInt(options.staleThreshold, 10), options.fix);
+        if (hasError)
+            process.exit(1);
+    });
+    map
+        .command("backfill")
+        .description("mutating unless --dry-run: incremental gap-fill for an already-indexed repo")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--dry-run", "non-mutating preview: print results without writing files")
+        .option("--domain <domain>", "Limit backfill to a specific domain")
+        .option("-v, --verbose", "Show per-file classification")
+        .action((options) => {
+        backfillHandler(options.repoRoot, options.dryRun ?? false, options.domain, options.verbose ?? false);
+    });
+    map
+        .command("query [path]")
+        .description("safe/read-only: sidecar metadata lookup by path, glob, or filter")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--domain <domain>", "All files in a domain")
+        .option("--taskchain <taskchain>", "All files in a taskchain")
+        .option("--text", "Human-readable output instead of JSON")
+        .option("--include-instructions", "Include POLARIS.md instruction file path and content in output")
+        .action((pathArg, options) => {
+        queryHandler(options.repoRoot, pathArg, options.domain, options.taskchain, options.text ?? false, options.includeInstructions ?? false);
+    });
+    map
+        .command("welfare-check")
+        .description("safe/read-only: run route welfare checks and report per-route health")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--route <path>", "Scope to a single route domain")
+        .action((options) => {
+        const report = (0, welfare_js_1.runWelfareCheck)(options.repoRoot, options.route);
+        (0, welfare_js_1.printWelfareCheckReport)(report);
+        if (report.needsReview > 0) {
+            process.exit(1);
+        }
+    });
+    return map;
+}

package/dist/map/inference.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferRoute = inferRoute;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function inferRoute(filePath, repoRoot, config, knownRoutes, branchName) {
+    let confidence = 0;
+    let domain = "";
+    let route = "";
+    let taskchain = "";
+    const tags = [];
+    // Signal 1: file path prefix matching sourceRoots
+    for (const sourceRoot of (config.repo.sourceRoots ?? [])) {
+        const prefix = sourceRoot.endsWith("/") ? sourceRoot : `${sourceRoot}/`;
+        if (filePath.startsWith(prefix)) {
+            const rest = filePath.slice(prefix.length);
+            const subdir = rest.split("/")[0];
+            if (subdir && rest.includes("/")) {
+                domain = subdir;
+                route = `${sourceRoot}/${subdir}`;
+                taskchain = `polaris-${subdir}`;
+                confidence += 0.85;
+                tags.push(subdir);
+            }
+            break;
+        }
+    }
+    // Signal 2: nearby mapped files in same directory (corroborating)
+    if (domain) {
+        const dir = (0, node_path_1.dirname)(filePath);
+        const nearbyAgreement = Object.entries(knownRoutes).some(([p, e]) => (0, node_path_1.dirname)(p) === dir && e.domain === domain);
+        if (nearbyAgreement) {
+            confidence = Math.min(confidence + 0.05, 0.99);
+        }
+    }
+    // Signal 3: branch name contains domain slug (corroborating)
+    if (domain && branchName) {
+        const slugParts = branchName.toLowerCase().split(/[-/]/);
+        if (slugParts.includes(domain.toLowerCase())) {
+            confidence = Math.min(confidence + 0.05, 0.99);
+        }
+    }
+    // Signal 4: file imports from paths in the same domain (corroborating)
+    if (domain) {
+        try {
+            const fullPath = (0, node_path_1.resolve)(repoRoot, filePath);
+            if ((0, node_fs_1.existsSync)(fullPath)) {
+                const content = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
+                const escapedDomain = domain.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                const sameDomainImport = new RegExp(`from\\s+['"](?:\\.\\.?/)*${escapedDomain}/`);
+                if (sameDomainImport.test(content)) {
+                    confidence = Math.min(confidence + 0.05, 0.99);
+                }
+            }
+        }
+        catch {
+            // ignore read errors
+        }
+    }
+    // Tags: entry-point and test detection
+    const file = (0, node_path_1.basename)(filePath);
+    if (file === "index.ts" || file === "index.js")
+        tags.push("entry-point");
+    if (file.includes(".test.") || file.includes(".spec."))
+        tags.push("test");
+    return {
+        domain: domain || "unknown",
+        route: route || filePath,
+        taskchain: taskchain || "polaris-core",
+        confidence,
+        tags,
+    };
+}

package/dist/map/inference.test.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const inference_js_1 = require("./inference.js");
+const defaults_js_1 = require("../config/defaults.js");
+const config = defaults_js_1.DEFAULT_CONFIG;
+(0, vitest_1.describe)("inferRoute", () => {
+    (0, vitest_1.it)("classifies a file under a sourceRoot subdirectory", () => {
+        const result = (0, inference_js_1.inferRoute)("src/cli/index.ts", "/repo", config, {}, "");
+        (0, vitest_1.expect)(result.domain).toBe("cli");
+        (0, vitest_1.expect)(result.route).toBe("src/cli");
+        (0, vitest_1.expect)(result.taskchain).toBe("polaris-cli");
+        (0, vitest_1.expect)(result.confidence).toBeGreaterThanOrEqual(0.85);
+        (0, vitest_1.expect)(result.tags).toContain("cli");
+        (0, vitest_1.expect)(result.tags).toContain("entry-point");
+    });
+    (0, vitest_1.it)("classifies a map domain file", () => {
+        const result = (0, inference_js_1.inferRoute)("src/map/atlas.ts", "/repo", config, {}, "");
+        (0, vitest_1.expect)(result.domain).toBe("map");
+        (0, vitest_1.expect)(result.confidence).toBeGreaterThanOrEqual(0.85);
+    });
+    (0, vitest_1.it)("returns low confidence for files outside sourceRoots", () => {
+        const result = (0, inference_js_1.inferRoute)("package.json", "/repo", config, {}, "");
+        (0, vitest_1.expect)(result.confidence).toBeLessThan(0.85);
+    });
+    (0, vitest_1.it)("tags test files", () => {
+        const result = (0, inference_js_1.inferRoute)("src/cli/version.test.ts", "/repo", config, {}, "");
+        (0, vitest_1.expect)(result.tags).toContain("test");
+    });
+    (0, vitest_1.it)("boosts confidence from branch name", () => {
+        const base = (0, inference_js_1.inferRoute)("src/map/index.ts", "/repo", config, {}, "");
+        const withBranch = (0, inference_js_1.inferRoute)("src/map/index.ts", "/repo", config, {}, "philmeaux/pol-4-cluster-3-polaris-map");
+        (0, vitest_1.expect)(withBranch.confidence).toBeGreaterThanOrEqual(base.confidence);
+    });
+});

package/dist/map/query.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMapQuery = runMapQuery;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const loader_js_1 = require("../config/loader.js");
+const parser_js_1 = require("../ignore/parser.js");
+const atlas_js_1 = require("./atlas.js");
+function globToRegex(pattern) {
+    let regStr = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i];
+        if (c === "*" && pattern[i + 1] === "*") {
+            regStr += ".*";
+            i += 2;
+            if (pattern[i] === "/")
+                i++;
+        }
+        else if (c === "*") {
+            regStr += "[^/]*";
+            i++;
+        }
+        else if (c === "?") {
+            regStr += "[^/]";
+            i++;
+        }
+        else if (".+^${}[]|()\\".includes(c)) {
+            regStr += "\\" + c;
+            i++;
+        }
+        else {
+            regStr += c;
+            i++;
+        }
+    }
+    return new RegExp("^" + regStr + "$");
+}
+function loadIgnoreFilter(repoRoot) {
+    let userPatterns = [];
+    try {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(repoRoot, ".polarisignore"), "utf-8");
+        userPatterns = raw.split(/\r?\n/).filter((line) => line.trim() !== "" && !line.startsWith("#"));
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && "code" in err && err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    return (0, parser_js_1.parsePolarisIgnore)(userPatterns);
+}
+function toQueryEntry(entry, repoRoot, includeInstructions) {
+    const base = {
+        domain: entry.domain,
+        route: entry.route,
+        taskchain: entry.taskchain,
+        confidence: entry.confidence,
+        classification: entry.classification === "needs-review" ? "needs-review" : "indexed",
+        last_updated: entry.last_updated,
+        tags: entry.tags,
+    };
+    if (entry.instructionFile !== undefined) {
+        base.instructionFile = entry.instructionFile;
+        if (includeInstructions && repoRoot !== undefined) {
+            try {
+                base.instructionContent = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(repoRoot, entry.instructionFile), "utf-8");
+            }
+            catch {
+                // file missing — omit content silently
+            }
+        }
+    }
+    return base;
+}
+function resolveEntry(filePath, routes, needsReview, exemptions, ig, repoRoot, includeInstructions) {
+    if (routes[filePath])
+        return toQueryEntry(routes[filePath], repoRoot, includeInstructions);
+    if (needsReview[filePath])
+        return toQueryEntry(needsReview[filePath], repoRoot, includeInstructions);
+    if (exemptions[filePath])
+        return { classification: exemptions[filePath].classification };
+    if (ig.ignores(filePath))
+        return { classification: "ignored" };
+    return { classification: "unmapped" };
+}
+function printText(result) {
+    for (const [filePath, entry] of Object.entries(result)) {
+        const parts = [filePath, entry.classification];
+        if ("domain" in entry) {
+            parts.push(`domain:${entry.domain}`, `route:${entry.route}`, `taskchain:${entry.taskchain}`, `conf:${entry.confidence.toFixed(2)}`);
+            if (entry.instructionFile !== undefined)
+                parts.push(`instructions:${entry.instructionFile}`);
+        }
+        console.log(parts.join("  "));
+    }
+}
+function runMapQuery(repoRoot, pathArg, domain, taskchain, textMode, includeInstructions = false) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const outputPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(outputPath, "file-routes.json"))) {
+        console.error("atlas not initialized — run `polaris map index` first");
+        process.exit(1);
+    }
+    const routes = (0, atlas_js_1.readFileRoutes)(outputPath);
+    const needsReview = (0, atlas_js_1.readNeedsReview)(outputPath);
+    const exemptions = (0, atlas_js_1.readExemptions)(outputPath);
+    const ig = loadIgnoreFilter(repoRoot);
+    const result = {};
+    if (domain !== undefined) {
+        for (const [filePath, entry] of [...Object.entries(routes), ...Object.entries(needsReview)]) {
+            if (entry.domain === domain)
+                result[filePath] = toQueryEntry(entry, repoRoot, includeInstructions);
+        }
+    }
+    else if (taskchain !== undefined) {
+        for (const [filePath, entry] of [...Object.entries(routes), ...Object.entries(needsReview)]) {
+            if (entry.taskchain === taskchain)
+                result[filePath] = toQueryEntry(entry, repoRoot, includeInstructions);
+        }
+    }
+    else if (pathArg !== undefined) {
+        const isGlobPattern = pathArg.includes("*") || pathArg.includes("?");
+        const isDir = !isGlobPattern && pathArg.endsWith("/");
+        if (isGlobPattern) {
+            const re = globToRegex(pathArg);
+            const allPaths = new Set([...Object.keys(routes), ...Object.keys(needsReview), ...Object.keys(exemptions)]);
+            for (const filePath of allPaths) {
+                if (re.test(filePath))
+                    result[filePath] = resolveEntry(filePath, routes, needsReview, exemptions, ig, repoRoot, includeInstructions);
+            }
+        }
+        else if (isDir) {
+            const prefix = pathArg;
+            const allPaths = new Set([...Object.keys(routes), ...Object.keys(needsReview), ...Object.keys(exemptions)]);
+            for (const filePath of allPaths) {
+                if (filePath.startsWith(prefix))
+                    result[filePath] = resolveEntry(filePath, routes, needsReview, exemptions, ig, repoRoot, includeInstructions);
+            }
+        }
+        else {
+            if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, pathArg))) {
+                process.stderr.write(`warn: file does not exist in repo: ${pathArg}\n`);
+            }
+            result[pathArg] = resolveEntry(pathArg, routes, needsReview, exemptions, ig, repoRoot, includeInstructions);
+        }
+    }
+    else {
+        console.error("polaris map query: specify a path, glob, or --domain/--taskchain filter");
+        process.exit(1);
+    }
+    if (textMode) {
+        printText(result);
+    }
+    else {
+        console.log(JSON.stringify(result, null, 2));
+    }
+}