@lsctech/polaris 0.1.0

package/dist/graph/resolver/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGraphResolver = runGraphResolver;
+const build_edges_js_1 = require("./build-edges.js");
+const resolve_imports_js_1 = require("./resolve-imports.js");
+function runGraphResolver(options) {
+    const db = options.graphStore.getDatabase();
+    db.exec("BEGIN IMMEDIATE TRANSACTION");
+    try {
+        (0, resolve_imports_js_1.clearResolverStubs)(db);
+        const resolvedImports = (0, resolve_imports_js_1.resolveImports)(db);
+        const built = (0, build_edges_js_1.buildEdges)(db, resolvedImports);
+        db.exec("COMMIT");
+        return {
+            ...built,
+            resolvedImports: resolvedImports.length,
+        };
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}

package/dist/graph/resolver/resolve-imports.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveImports = resolveImports;
+exports.clearResolverStubs = clearResolverStubs;
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const queries_js_1 = require("../store/queries.js");
+const UNRESOLVED_FILE_PREFIX = "file-unresolved-";
+const UNRESOLVED_NODE_PREFIX = "node-unresolved-";
+const UNRESOLVED_SYMBOL_PREFIX = "symbol-unresolved-";
+const UNRESOLVED_PATH_PREFIX = "unresolved://";
+const UNRESOLVED_SIGNATURE = "__UNRESOLVED__";
+function resolveImports(db) {
+    const files = db
+        .prepare(`
+        SELECT id, path
+        FROM files
+      `)
+        .all();
+    const byPath = new Map();
+    for (const file of files) {
+        byPath.set((0, node_path_1.normalize)(file.path), file);
+    }
+    const exportedByFileId = new Map();
+    const symbols = db
+        .prepare(`
+        SELECT id, file_id AS fileId, name, exported
+        FROM symbols
+        WHERE kind != 'import'
+      `)
+        .all();
+    for (const symbol of symbols) {
+        if (symbol.exported !== 1) {
+            continue;
+        }
+        const existing = exportedByFileId.get(symbol.fileId) ?? [];
+        existing.push(symbol.id);
+        exportedByFileId.set(symbol.fileId, existing);
+    }
+    for (const symbolIds of exportedByFileId.values()) {
+        symbolIds.sort((left, right) => left.localeCompare(right));
+    }
+    const imports = db
+        .prepare(`
+        SELECT
+          s.id AS symbolId,
+          s.file_id AS importerFileId,
+          f.path AS importerFilePath,
+          s.name AS specifier
+        FROM symbols s
+        JOIN files f ON f.id = s.file_id
+        WHERE s.kind = 'import'
+        ORDER BY f.path, s.name, s.id
+      `)
+        .all();
+    const resolvedImports = [];
+    for (const entry of imports) {
+        const resolvedFile = resolveImportSpecifier(entry.importerFilePath, entry.specifier, byPath);
+        if (resolvedFile) {
+            const resolvedSymbolIds = exportedByFileId.get(resolvedFile.id) ?? [];
+            const unresolved = resolvedSymbolIds.length === 0;
+            resolvedImports.push({
+                importSymbolId: entry.symbolId,
+                importSpecifier: entry.specifier,
+                importerFileId: entry.importerFileId,
+                importerFilePath: entry.importerFilePath,
+                resolvedFileId: resolvedFile.id,
+                resolvedFilePath: resolvedFile.path,
+                resolvedSymbolIds,
+                unresolved,
+            });
+            continue;
+        }
+        const unresolvedTarget = upsertUnresolvedImportStub(db, entry);
+        resolvedImports.push({
+            importSymbolId: entry.symbolId,
+            importSpecifier: entry.specifier,
+            importerFileId: entry.importerFileId,
+            importerFilePath: entry.importerFilePath,
+            resolvedFileId: unresolvedTarget.file.id,
+            resolvedFilePath: unresolvedTarget.file.path,
+            resolvedSymbolIds: [unresolvedTarget.symbol.id],
+            unresolved: true,
+        });
+    }
+    return resolvedImports;
+}
+function clearResolverStubs(db) {
+    db.prepare("DELETE FROM edges WHERE type IN ('CALLS', 'IMPORTS', 'DEFINED_IN')").run();
+    db.prepare("DELETE FROM symbols WHERE id LIKE ?1").run(`${UNRESOLVED_SYMBOL_PREFIX}%`);
+    db.prepare("DELETE FROM nodes WHERE id LIKE ?1").run(`${UNRESOLVED_NODE_PREFIX}%`);
+    db.prepare("DELETE FROM files WHERE id LIKE ?1 OR path LIKE ?2").run(`${UNRESOLVED_FILE_PREFIX}%`, `${UNRESOLVED_PATH_PREFIX}%`);
+}
+function upsertUnresolvedImportStub(db, row) {
+    const digest = makeDigest(`${row.importerFilePath}:${row.specifier}`);
+    const fileId = `${UNRESOLVED_FILE_PREFIX}${digest}`;
+    const filePath = `${UNRESOLVED_PATH_PREFIX}${row.importerFilePath}::${row.specifier}`;
+    const nodeId = `${UNRESOLVED_NODE_PREFIX}${digest}`;
+    const symbolId = `${UNRESOLVED_SYMBOL_PREFIX}${digest}`;
+    db.prepare(`
+      INSERT INTO files (id, path, language)
+      VALUES (?1, ?2, ?3)
+      ON CONFLICT(id) DO UPDATE SET
+        path = excluded.path,
+        language = excluded.language
+    `).run(fileId, filePath, "unknown");
+    const node = {
+        id: nodeId,
+        type: "IMPORT",
+        fileId,
+        name: `UNRESOLVED:${row.specifier}`,
+    };
+    (0, queries_js_1.insertNode)(db, node);
+    db.prepare(`
+      INSERT INTO symbols (id, node_id, file_id, name, kind, signature, exported)
+      VALUES (?1, ?2, ?3, ?4, ?5, ?6, 0)
+      ON CONFLICT(id) DO UPDATE SET
+        node_id = excluded.node_id,
+        file_id = excluded.file_id,
+        name = excluded.name,
+        kind = excluded.kind,
+        signature = excluded.signature,
+        exported = excluded.exported
+    `).run(symbolId, nodeId, fileId, row.specifier, "unknown", UNRESOLVED_SIGNATURE);
+    return {
+        file: {
+            id: fileId,
+            path: filePath,
+        },
+        symbol: {
+            id: symbolId,
+            nodeId,
+            fileId,
+            name: row.specifier,
+            kind: "unknown",
+            signature: UNRESOLVED_SIGNATURE,
+            exported: false,
+        },
+    };
+}
+function resolveImportSpecifier(importerPath, specifier, byPath) {
+    if (!specifier.startsWith(".")) {
+        return null;
+    }
+    const importerDir = (0, node_path_1.dirname)(importerPath);
+    const candidates = new Set();
+    const base = (0, node_path_1.normalize)((0, node_path_1.resolve)(importerDir, specifier));
+    candidates.add(base);
+    const ext = (0, node_path_1.extname)(base);
+    if (!ext) {
+        for (const extension of [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]) {
+            candidates.add(`${base}${extension}`);
+        }
+        for (const extension of ["/index.ts", "/index.tsx", "/index.js", "/index.jsx", "/index.mjs", "/index.cjs"]) {
+            candidates.add(`${base}${extension}`);
+        }
+    }
+    for (const candidate of candidates) {
+        const found = byPath.get(candidate);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
+function makeDigest(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(input).digest("hex").slice(0, 24);
+}

package/dist/graph/store/adapter.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphStoreAdapter = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_sqlite_1 = require("node:sqlite");
+const governance_js_1 = require("../governance.js");
+const types_js_1 = require("./types.js");
+const MIT_NOTICE = "Includes concepts derived from an MIT-licensed graph indexing approach.";
+const FALLBACK_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS files (
+  id TEXT PRIMARY KEY,
+  path TEXT NOT NULL UNIQUE,
+  language TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS nodes (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  file_id TEXT NOT NULL,
+  name TEXT,
+  start_line INTEGER,
+  start_column INTEGER,
+  end_line INTEGER,
+  end_column INTEGER,
+  FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS symbols (
+  id TEXT PRIMARY KEY,
+  node_id TEXT NOT NULL UNIQUE,
+  file_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  signature TEXT,
+  exported INTEGER NOT NULL DEFAULT 0 CHECK (exported IN (0, 1)),
+  FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE,
+  FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  from_node_id TEXT NOT NULL,
+  to_node_id TEXT NOT NULL,
+  metadata TEXT,
+  FOREIGN KEY (from_node_id) REFERENCES nodes(id) ON DELETE CASCADE,
+  FOREIGN KEY (to_node_id) REFERENCES nodes(id) ON DELETE CASCADE,
+  UNIQUE (type, from_node_id, to_node_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_nodes_file_id ON nodes(file_id);
+CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+CREATE INDEX IF NOT EXISTS idx_symbols_file_id ON symbols(file_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from_node_id ON edges(from_node_id);
+CREATE INDEX IF NOT EXISTS idx_edges_to_node_id ON edges(to_node_id);
+`;
+class GraphStoreAdapter {
+    dbPath;
+    noticesOutputPath;
+    db = null;
+    initialized = false;
+    constructor(options) {
+        this.dbPath = (0, node_path_1.resolve)(options.repoRoot ?? process.cwd(), options.dbPath);
+        this.noticesOutputPath = (0, node_path_1.resolve)(options.repoRoot ?? process.cwd(), options.graphOutputPath ?? ".polaris/graph");
+    }
+    open() {
+        if (this.db) {
+            return this.db;
+        }
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.dbPath), { recursive: true });
+        this.db = new node_sqlite_1.DatabaseSync(this.dbPath);
+        this.db.exec("PRAGMA foreign_keys = ON;");
+        this.initSchema();
+        return this.db;
+    }
+    close() {
+        if (!this.db) {
+            return;
+        }
+        this.db.close();
+        this.db = null;
+    }
+    getDatabase() {
+        if (!this.db) {
+            throw new Error("Graph store is not open.");
+        }
+        return this.db;
+    }
+    initSchema() {
+        const db = this.getDatabase();
+        db.exec(loadSchemaSql());
+        const appliedVersion = getAppliedSchemaVersion(db);
+        if (appliedVersion > types_js_1.CURRENT_GRAPH_SCHEMA_VERSION) {
+            throw new Error(`Graph schema version ${appliedVersion} is newer than supported ${types_js_1.CURRENT_GRAPH_SCHEMA_VERSION}.`);
+        }
+        for (let version = appliedVersion + 1; version <= types_js_1.CURRENT_GRAPH_SCHEMA_VERSION; version += 1) {
+            db.prepare(`
+          INSERT OR IGNORE INTO schema_version (version, applied_at)
+          VALUES (?1, CURRENT_TIMESTAMP)
+        `).run(version);
+        }
+        if (!this.initialized) {
+            (0, governance_js_1.writeGraphNotices)(this.noticesOutputPath, [MIT_NOTICE]);
+            this.initialized = true;
+        }
+    }
+}
+exports.GraphStoreAdapter = GraphStoreAdapter;
+function loadSchemaSql() {
+    const schemaPath = (0, node_path_1.resolve)(__dirname, "schema.sql");
+    try {
+        return (0, node_fs_1.readFileSync)(schemaPath, "utf-8");
+    }
+    catch {
+        return FALLBACK_SCHEMA_SQL;
+    }
+}
+function getAppliedSchemaVersion(db) {
+    const row = db
+        .prepare(`
+        SELECT MAX(version) AS version
+        FROM schema_version
+      `)
+        .get();
+    return row?.version ?? 0;
+}

package/dist/graph/store/queries.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insertNode = insertNode;
+exports.insertEdge = insertEdge;
+exports.lookupSymbol = lookupSymbol;
+exports.lookupFile = lookupFile;
+function insertNode(db, node) {
+    db.prepare(`
+      INSERT INTO nodes (
+        id,
+        type,
+        file_id,
+        name,
+        start_line,
+        start_column,
+        end_line,
+        end_column
+      ) VALUES (
+        @id,
+        @type,
+        @fileId,
+        @name,
+        @startLine,
+        @startColumn,
+        @endLine,
+        @endColumn
+      )
+      ON CONFLICT(id) DO UPDATE SET
+        type = excluded.type,
+        file_id = excluded.file_id,
+        name = excluded.name,
+        start_line = excluded.start_line,
+        start_column = excluded.start_column,
+        end_line = excluded.end_line,
+        end_column = excluded.end_column
+    `).run({
+        id: node.id,
+        type: node.type,
+        fileId: node.fileId,
+        name: node.name ?? null,
+        startLine: node.startLine ?? null,
+        startColumn: node.startColumn ?? null,
+        endLine: node.endLine ?? null,
+        endColumn: node.endColumn ?? null,
+    });
+}
+function insertEdge(db, edge) {
+    db.prepare(`
+      INSERT INTO edges (
+        id,
+        type,
+        from_node_id,
+        to_node_id,
+        metadata
+      ) VALUES (
+        @id,
+        @type,
+        @fromNodeId,
+        @toNodeId,
+        @metadata
+      )
+      ON CONFLICT(id) DO UPDATE SET
+        type = excluded.type,
+        from_node_id = excluded.from_node_id,
+        to_node_id = excluded.to_node_id,
+        metadata = excluded.metadata
+    `).run({
+        id: edge.id,
+        type: edge.type,
+        fromNodeId: edge.fromNodeId,
+        toNodeId: edge.toNodeId,
+        metadata: edge.metadata ?? null,
+    });
+}
+function lookupSymbol(db, name, filePath) {
+    const row = db
+        .prepare(`
+        SELECT
+          s.id,
+          s.node_id AS nodeId,
+          s.file_id AS fileId,
+          s.name,
+          s.kind,
+          s.signature,
+          s.exported
+        FROM symbols s
+        JOIN files f ON f.id = s.file_id
+        WHERE s.name = ?1
+          AND (?2 IS NULL OR f.path = ?2)
+        ORDER BY s.id
+        LIMIT 1
+      `)
+        .get(name, filePath ?? null);
+    if (!row) {
+        return null;
+    }
+    return {
+        id: row.id,
+        nodeId: row.nodeId,
+        fileId: row.fileId,
+        name: row.name,
+        kind: row.kind,
+        signature: row.signature,
+        exported: row.exported === 1,
+    };
+}
+function lookupFile(db, filePath) {
+    const row = db
+        .prepare(`
+        SELECT id, path, language
+        FROM files
+        WHERE path = ?1
+        LIMIT 1
+      `)
+        .get(filePath);
+    if (!row) {
+        return null;
+    }
+    return {
+        id: row.id,
+        path: row.path,
+        language: row.language,
+    };
+}

package/dist/graph/store/types.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_GRAPH_SCHEMA_VERSION = void 0;
+exports.CURRENT_GRAPH_SCHEMA_VERSION = 1;

package/dist/ignore/defaults.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECRET_PATTERNS = exports.DEFAULT_EXCLUSIONS = void 0;
+exports.DEFAULT_EXCLUSIONS = [
+    // Package managers
+    "node_modules/",
+    ".pnpm-store/",
+    "vendor/",
+    "Pods/",
+    // Build artifacts
+    "build/",
+    "dist/",
+    ".build/",
+    "DerivedData/",
+    "*.xcarchive",
+    // Language-specific caches
+    ".dart_tool/",
+    ".pub-cache/",
+    "__pycache__/",
+    "*.pyc",
+    ".gradle/",
+    // IDE / editor
+    ".idea/",
+    ".vscode/",
+    "*.xcworkspace",
+    // Secrets (always enforced, cannot be negated)
+    "*.pem",
+    "*.key",
+    "*.env",
+    ".env.*",
+    "credentials.json",
+    // VCS
+    ".git/",
+];
+exports.SECRET_PATTERNS = [
+    "*.pem",
+    "*.key",
+    "*.env",
+    ".env.*",
+    "credentials.json",
+];

package/dist/ignore/parser.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePolarisIgnore = parsePolarisIgnore;
+exports.isIgnored = isIgnored;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ignore_1 = __importDefault(require("ignore"));
+const defaults_js_1 = require("./defaults.js");
+function parsePolarisIgnore(userPatterns) {
+    const ig = (0, ignore_1.default)();
+    // User patterns first so SECRET_PATTERNS applied after cannot be negated
+    ig.add(userPatterns);
+    ig.add(defaults_js_1.DEFAULT_EXCLUSIONS);
+    ig.add(defaults_js_1.SECRET_PATTERNS);
+    return ig;
+}
+function isIgnored(filePath, repoRoot) {
+    const ig = (0, ignore_1.default)();
+    ig.add(defaults_js_1.DEFAULT_EXCLUSIONS);
+    const ignorePath = (0, node_path_1.resolve)(repoRoot, ".polarisignore");
+    try {
+        const raw = (0, node_fs_1.readFileSync)(ignorePath, "utf-8");
+        const userPatterns = raw.split(/\r?\n/).filter((line) => line.trim() !== "" && !line.startsWith("#"));
+        // Apply non-secret user patterns first
+        const nonSecretPatterns = userPatterns.filter((p) => !defaults_js_1.SECRET_PATTERNS.includes(p));
+        ig.add(nonSecretPatterns);
+        // Re-add secret patterns so they cannot be negated
+        ig.add(defaults_js_1.SECRET_PATTERNS);
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && "code" in err && err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    return ig.ignores(filePath);
+}

package/dist/lint/map-reference-validator.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSkillChainFile = validateSkillChainFile;
+exports.validateSkillChainDirectory = validateSkillChainDirectory;
+exports.validateMapReferences = validateMapReferences;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Patterns that indicate broad context preload in skill chain files.
+ * These patterns violate the Navigation Before Retrieval doctrine.
+ */
+const BROAD_PRELOAD_PATTERNS = [
+    /read\s+all\s+doctrine/i,
+    /load\s+all\s+charts/i,
+    /preload\s+(all\s+)?(linked\s+)?(docs|documents|doctrine|charts)/i,
+];
+function validateSkillChainFile(filePath) {
+    const violations = [];
+    try {
+        const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const lineNumber = i + 1;
+            for (const pattern of BROAD_PRELOAD_PATTERNS) {
+                if (pattern.test(line)) {
+                    violations.push({
+                        file: filePath,
+                        line: lineNumber,
+                        message: "[navigation-before-retrieval] Skill chain instructs broad context preload — use targeted retrieval instead",
+                        rule: "navigation-before-retrieval",
+                    });
+                    break; // Only report one violation per line
+                }
+            }
+        }
+    }
+    catch (error) {
+        // If we can't read the file, skip it
+        console.warn(`Warning: Could not read file ${filePath}: ${error}`);
+    }
+    return violations;
+}
+function validateSkillChainDirectory(dirPath) {
+    const violations = [];
+    let filesChecked = 0;
+    try {
+        const entries = (0, node_fs_1.readdirSync)(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = (0, node_path_1.join)(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                // Recursively check subdirectories
+                const result = validateSkillChainDirectory(fullPath);
+                violations.push(...result.violations);
+                filesChecked += result.filesChecked;
+            }
+            else if (entry.name === "chain.md") {
+                // Check skill chain files
+                filesChecked++;
+                violations.push(...validateSkillChainFile(fullPath));
+            }
+        }
+    }
+    catch (error) {
+        console.warn(`Warning: Could not read directory ${dirPath}: ${error}`);
+    }
+    return { violations, filesChecked };
+}
+function validateMapReferences(repoRoot) {
+    const skillsDir = (0, node_path_1.join)(repoRoot, ".polaris", "skills");
+    return validateSkillChainDirectory(skillsDir);
+}