@lsctech/polaris 0.1.0

package/dist/graph/adapter/swift/runtime.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTreeSitterRuntime = loadTreeSitterRuntime;
+let cachedRuntime = null;
+let cachedRuntimePromise = null;
+async function loadTreeSitterRuntime() {
+    if (cachedRuntime) {
+        return cachedRuntime;
+    }
+    if (cachedRuntimePromise) {
+        return await cachedRuntimePromise;
+    }
+    cachedRuntimePromise = (async () => {
+        const loaded = await loadTreeSitterModules();
+        const parser = new loaded.parserConstructor();
+        parser.setLanguage(loaded.language);
+        const runtime = {
+            parse(source) {
+                return parser.parse(source);
+            },
+        };
+        cachedRuntime = runtime;
+        cachedRuntimePromise = null;
+        return runtime;
+    })();
+    return await cachedRuntimePromise;
+}
+async function loadTreeSitterModules() {
+    const dynamicImport = createDynamicImporter();
+    const [treeSitterModule, swiftModule] = await Promise.all([
+        dynamicImport("tree-sitter"),
+        dynamicImport("tree-sitter-swift"),
+    ]);
+    return {
+        parserConstructor: resolveParserConstructor(treeSitterModule),
+        language: resolveGrammar(swiftModule, "tree-sitter-swift"),
+    };
+}
+function createDynamicImporter() {
+    const importer = new Function("specifier", "return import(specifier);");
+    return (specifier) => importer(specifier);
+}
+function resolveParserConstructor(moduleValue) {
+    if (typeof moduleValue === "function") {
+        return moduleValue;
+    }
+    if (moduleValue && typeof moduleValue === "object") {
+        const directDefault = moduleValue.default;
+        if (typeof directDefault === "function") {
+            return directDefault;
+        }
+        const namedParser = moduleValue.Parser;
+        if (typeof namedParser === "function") {
+            return namedParser;
+        }
+    }
+    throw new Error("Unable to resolve tree-sitter parser constructor.");
+}
+function resolveGrammar(moduleValue, packageName) {
+    if (moduleValue && typeof moduleValue === "object") {
+        const directDefault = moduleValue.default;
+        if (directDefault) {
+            return directDefault;
+        }
+    }
+    if (moduleValue) {
+        return moduleValue;
+    }
+    throw new Error(`Unable to resolve ${packageName} grammar.`);
+}

package/dist/graph/adapter/types.js

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

package/dist/graph/adapter/typescript-javascript/adapter.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeScriptJavaScriptAdapter = void 0;
+exports.createTypeScriptJavaScriptAdapter = createTypeScriptJavaScriptAdapter;
+const node_path_1 = require("node:path");
+const extract_js_1 = require("./extract.js");
+const runtime_js_1 = require("./runtime.js");
+const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+class TypeScriptJavaScriptAdapter {
+    loadRuntime;
+    languageId = "typescript-javascript";
+    fileExtensions = DEFAULT_EXTENSIONS;
+    confidence = "high";
+    limitations = [
+        "Extracts declaration-level symbols only (functions, classes, methods, imports).",
+        "Does not resolve runtime module graph semantics beyond extension normalization.",
+    ];
+    constructor(loadRuntime) {
+        this.loadRuntime = loadRuntime;
+    }
+    async extractSymbols(filePath, source) {
+        const language = detectLanguage(filePath);
+        if (!language) {
+            throw new Error(`Unsupported TypeScript/JavaScript file extension: ${(0, node_path_1.extname)(filePath)}`);
+        }
+        const runtime = await this.loadRuntime();
+        const tree = runtime.parse(source, language);
+        return (0, extract_js_1.extractTypeScriptJavaScriptSymbolsFromTree)(tree, language);
+    }
+    resolveImportSpecifier(specifier, context) {
+        if (specifier.length === 0) {
+            return null;
+        }
+        if (!specifier.startsWith(".")) {
+            return specifier;
+        }
+        if ((0, node_path_1.extname)(specifier).length > 0) {
+            return specifier;
+        }
+        const candidateExtensions = context.candidateExtensions?.length
+            ? context.candidateExtensions
+            : [preferredExtensionForFile(context.fromFilePath)];
+        return `${specifier}${candidateExtensions[0]}`;
+    }
+}
+exports.TypeScriptJavaScriptAdapter = TypeScriptJavaScriptAdapter;
+function createTypeScriptJavaScriptAdapter(options = {}) {
+    return new TypeScriptJavaScriptAdapter(options.loadRuntime ?? runtime_js_1.loadTreeSitterRuntime);
+}
+function detectLanguage(filePath) {
+    const extension = (0, node_path_1.extname)(filePath).toLowerCase();
+    if (extension === ".ts" || extension === ".tsx") {
+        return "typescript";
+    }
+    if (extension === ".js" ||
+        extension === ".jsx" ||
+        extension === ".mjs" ||
+        extension === ".cjs") {
+        return "javascript";
+    }
+    return null;
+}
+function preferredExtensionForFile(filePath) {
+    const extension = (0, node_path_1.extname)(filePath).toLowerCase();
+    if (extension === ".ts" || extension === ".tsx") {
+        return ".ts";
+    }
+    if (extension === ".js" || extension === ".jsx" || extension === ".mjs" || extension === ".cjs") {
+        return ".js";
+    }
+    return ".ts";
+}

package/dist/graph/adapter/typescript-javascript/extract.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTypeScriptJavaScriptSymbolsFromTree = extractTypeScriptJavaScriptSymbolsFromTree;
+function extractTypeScriptJavaScriptSymbolsFromTree(tree, language) {
+    const symbols = [];
+    walkNode(tree.rootNode, symbols);
+    const deduped = dedupeSymbols(symbols);
+    deduped.sort(compareExtractedSymbols);
+    return {
+        language,
+        symbols: deduped,
+    };
+}
+function walkNode(node, output) {
+    const current = toExtractedSymbol(node);
+    if (current) {
+        output.push(current);
+    }
+    for (const child of node.namedChildren ?? []) {
+        walkNode(child, output);
+    }
+}
+function toExtractedSymbol(node) {
+    switch (node.type) {
+        case "function_declaration":
+            return buildSymbol(node, "function", extractIdentifierName(node), sanitizeSignature(node.text));
+        case "class_declaration":
+            return buildSymbol(node, "class", extractIdentifierName(node), null);
+        case "method_definition":
+        case "method_signature":
+        case "abstract_method_signature":
+            return buildSymbol(node, "method", extractIdentifierName(node), sanitizeSignature(node.text));
+        case "import_statement":
+            return buildSymbol(node, "import", extractImportSource(node), null);
+        default:
+            return null;
+    }
+}
+function buildSymbol(node, kind, name, signature) {
+    if (!name) {
+        return null;
+    }
+    return {
+        kind,
+        name,
+        signature,
+        exported: isExported(node),
+        startLine: node.startPosition.row + 1,
+        startColumn: node.startPosition.column,
+        endLine: node.endPosition.row + 1,
+        endColumn: node.endPosition.column,
+    };
+}
+function extractIdentifierName(node) {
+    const byField = node.childForFieldName?.("name");
+    if (byField?.text) {
+        return byField.text.trim();
+    }
+    for (const child of node.namedChildren ?? []) {
+        if (IDENTIFIER_NODE_TYPES.has(child.type) && child.text.trim().length > 0) {
+            return child.text.trim();
+        }
+    }
+    return null;
+}
+function extractImportSource(node) {
+    const sourceNode = node.childForFieldName?.("source");
+    const raw = sourceNode?.text ?? node.text;
+    const match = raw.match(/["']([^"']+)["']/);
+    return match?.[1] ?? null;
+}
+function isExported(node) {
+    if (node.type.startsWith("export_")) {
+        return true;
+    }
+    if (node.text.startsWith("export ")) {
+        return true;
+    }
+    let current = node.parent ?? null;
+    while (current) {
+        if (current.type.startsWith("export_")) {
+            return true;
+        }
+        current = current.parent ?? null;
+    }
+    return false;
+}
+function sanitizeSignature(signature) {
+    const compact = signature.replace(/\s+/g, " ").trim();
+    return compact.length === 0 ? null : compact;
+}
+function dedupeSymbols(symbols) {
+    const byFingerprint = new Map();
+    for (const symbol of symbols) {
+        const fingerprint = [
+            symbol.kind,
+            symbol.name,
+            symbol.startLine,
+            symbol.startColumn,
+            symbol.endLine,
+            symbol.endColumn,
+        ].join(":");
+        byFingerprint.set(fingerprint, symbol);
+    }
+    return Array.from(byFingerprint.values());
+}
+function compareExtractedSymbols(left, right) {
+    return (left.startLine - right.startLine ||
+        left.startColumn - right.startColumn ||
+        left.endLine - right.endLine ||
+        left.endColumn - right.endColumn ||
+        left.kind.localeCompare(right.kind) ||
+        left.name.localeCompare(right.name));
+}
+const IDENTIFIER_NODE_TYPES = new Set(["identifier", "property_identifier", "private_property_identifier"]);

package/dist/graph/adapter/typescript-javascript/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTreeSitterRuntime = exports.extractTypeScriptJavaScriptSymbolsFromTree = exports.TypeScriptJavaScriptAdapter = exports.createTypeScriptJavaScriptAdapter = void 0;
+var adapter_js_1 = require("./adapter.js");
+Object.defineProperty(exports, "createTypeScriptJavaScriptAdapter", { enumerable: true, get: function () { return adapter_js_1.createTypeScriptJavaScriptAdapter; } });
+Object.defineProperty(exports, "TypeScriptJavaScriptAdapter", { enumerable: true, get: function () { return adapter_js_1.TypeScriptJavaScriptAdapter; } });
+var extract_js_1 = require("./extract.js");
+Object.defineProperty(exports, "extractTypeScriptJavaScriptSymbolsFromTree", { enumerable: true, get: function () { return extract_js_1.extractTypeScriptJavaScriptSymbolsFromTree; } });
+var runtime_js_1 = require("./runtime.js");
+Object.defineProperty(exports, "loadTreeSitterRuntime", { enumerable: true, get: function () { return runtime_js_1.loadTreeSitterRuntime; } });

package/dist/graph/adapter/typescript-javascript/runtime.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTreeSitterRuntime = loadTreeSitterRuntime;
+let cachedRuntime = null;
+async function loadTreeSitterRuntime() {
+    if (cachedRuntime) {
+        return cachedRuntime;
+    }
+    const loaded = await loadTreeSitterModules();
+    const parserByLanguage = new Map();
+    cachedRuntime = {
+        parse(source, language) {
+            const parser = getOrCreateParser(language, loaded, parserByLanguage);
+            return parser.parse(source);
+        },
+    };
+    return cachedRuntime;
+}
+function getOrCreateParser(language, loaded, parserByLanguage) {
+    const existing = parserByLanguage.get(language);
+    if (existing) {
+        return existing;
+    }
+    const parser = new loaded.parserConstructor();
+    const grammar = loaded.languages[language];
+    parser.setLanguage(grammar);
+    parserByLanguage.set(language, parser);
+    return parser;
+}
+async function loadTreeSitterModules() {
+    const dynamicImport = createDynamicImporter();
+    const [treeSitterModule, typeScriptModule, javaScriptModule] = await Promise.all([
+        dynamicImport("tree-sitter"),
+        dynamicImport("@tree-sitter/typescript"),
+        dynamicImport("@tree-sitter/javascript"),
+    ]);
+    const parserConstructor = resolveParserConstructor(treeSitterModule);
+    const typeScriptGrammar = resolveTypeScriptGrammar(typeScriptModule);
+    const javaScriptGrammar = resolveJavaScriptGrammar(javaScriptModule);
+    return {
+        parserConstructor,
+        languages: {
+            typescript: typeScriptGrammar,
+            javascript: javaScriptGrammar,
+        },
+    };
+}
+function createDynamicImporter() {
+    const importer = new Function("specifier", "return import(specifier);");
+    return (specifier) => importer(specifier);
+}
+function resolveParserConstructor(moduleValue) {
+    if (typeof moduleValue === "function") {
+        return moduleValue;
+    }
+    if (moduleValue && typeof moduleValue === "object") {
+        const directDefault = moduleValue.default;
+        if (typeof directDefault === "function") {
+            return directDefault;
+        }
+        const namedParser = moduleValue.Parser;
+        if (typeof namedParser === "function") {
+            return namedParser;
+        }
+    }
+    throw new Error("Unable to resolve tree-sitter parser constructor.");
+}
+function resolveTypeScriptGrammar(moduleValue) {
+    if (moduleValue && typeof moduleValue === "object") {
+        const direct = moduleValue;
+        if (direct.typescript) {
+            return direct.typescript;
+        }
+        if (direct.default && typeof direct.default === "object" && "typescript" in direct.default) {
+            return direct.default.typescript;
+        }
+        if (direct.default) {
+            return direct.default;
+        }
+    }
+    throw new Error("Unable to resolve @tree-sitter/typescript grammar.");
+}
+function resolveJavaScriptGrammar(moduleValue) {
+    if (moduleValue && typeof moduleValue === "object") {
+        const direct = moduleValue;
+        if (direct.javascript) {
+            return direct.javascript;
+        }
+        if (direct.default && typeof direct.default === "object" && "javascript" in direct.default) {
+            return direct.default.javascript;
+        }
+        if (direct.default) {
+            return direct.default;
+        }
+    }
+    throw new Error("Unable to resolve @tree-sitter/javascript grammar.");
+}

package/dist/graph/capability/index.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphCapabilityRegistry = void 0;
+class GraphCapabilityRegistry {
+    coverage = new Map();
+    supportedLanguages;
+    unsupportedExtensions = new Set();
+    fallbackFileCount = 0;
+    constructor(supportedLanguages) {
+        this.supportedLanguages = Array.from(new Set(supportedLanguages)).sort((left, right) => left.localeCompare(right));
+        for (const languageId of this.supportedLanguages) {
+            this.coverage.set(languageId, createEmptyCoverageEntry());
+        }
+    }
+    static unsupportedLanguageId(extension) {
+        return `unsupported:${normalizeExtension(extension)}`;
+    }
+    noteUnsupportedExtension(extension) {
+        this.unsupportedExtensions.add(normalizeExtension(extension));
+    }
+    recordSymbolLevel(languageId, symbolsExtracted, warnings = []) {
+        const entry = this.ensureEntry(languageId);
+        entry.filesDiscovered += 1;
+        entry.filesSymbolLevel += 1;
+        entry.symbolsExtracted += symbolsExtracted;
+        for (const warning of warnings) {
+            entry.warnings.push(warning);
+        }
+    }
+    recordFileLevel(languageId, warnings = []) {
+        const entry = this.ensureEntry(languageId);
+        entry.filesDiscovered += 1;
+        entry.filesFileLevel += 1;
+        this.fallbackFileCount += 1;
+        for (const warning of warnings) {
+            entry.warnings.push(warning);
+        }
+    }
+    recordFailure(languageId, warning) {
+        const entry = this.ensureEntry(languageId);
+        entry.filesDiscovered += 1;
+        entry.filesFailed += 1;
+        entry.warnings.push(warning);
+    }
+    buildReport() {
+        const entries = Array.from(this.coverage.entries()).sort(([left], [right]) => left.localeCompare(right));
+        const coverage = {};
+        let filesDiscovered = 0;
+        let filesSymbolLevel = 0;
+        let filesFileLevel = 0;
+        for (const [languageId, entry] of entries) {
+            coverage[languageId] = {
+                filesDiscovered: entry.filesDiscovered,
+                filesSymbolLevel: entry.filesSymbolLevel,
+                filesFileLevel: entry.filesFileLevel,
+                filesFailed: entry.filesFailed,
+                symbolsExtracted: entry.symbolsExtracted,
+                warnings: [...entry.warnings],
+            };
+            filesDiscovered += entry.filesDiscovered;
+            filesSymbolLevel += entry.filesSymbolLevel;
+            filesFileLevel += entry.filesFileLevel;
+        }
+        return {
+            supportedLanguages: [...this.supportedLanguages],
+            coverage,
+            unsupportedExtensions: Array.from(this.unsupportedExtensions).sort((left, right) => left.localeCompare(right)),
+            fallbackFileCount: this.fallbackFileCount,
+            symbolLevelPercent: toPercent(filesSymbolLevel, filesDiscovered),
+            totalCoveragePercent: toPercent(filesSymbolLevel + filesFileLevel, filesDiscovered),
+        };
+    }
+    ensureEntry(languageId) {
+        let entry = this.coverage.get(languageId);
+        if (!entry) {
+            entry = createEmptyCoverageEntry();
+            this.coverage.set(languageId, entry);
+        }
+        return entry;
+    }
+}
+exports.GraphCapabilityRegistry = GraphCapabilityRegistry;
+function createEmptyCoverageEntry() {
+    return {
+        filesDiscovered: 0,
+        filesSymbolLevel: 0,
+        filesFileLevel: 0,
+        filesFailed: 0,
+        symbolsExtracted: 0,
+        warnings: [],
+    };
+}
+function normalizeExtension(extension) {
+    const normalized = extension.trim().toLowerCase();
+    if (!normalized) {
+        return "<none>";
+    }
+    return normalized.startsWith(".") ? normalized : `.${normalized}`;
+}
+function toPercent(coveredFiles, discoveredFiles) {
+    if (discoveredFiles <= 0) {
+        return 0;
+    }
+    return Math.round((coveredFiles / discoveredFiles) * 1000) / 10;
+}

package/dist/graph/governance.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeGraphNotices = writeGraphNotices;
+exports.checkGraphInvalidation = checkGraphInvalidation;
+exports.recordGraphGovernanceState = recordGraphGovernanceState;
+exports.hashConfig = hashConfig;
+exports.resolveHeadCommit = resolveHeadCommit;
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const DEFAULT_GRAPH_OUTPUT_PATH = ".polaris/graph";
+const DEFAULT_INVALIDATION_TRIGGERS = [
+    "repo-change",
+    "config-change",
+];
+const NOTICES_FILE_NAME = "NOTICES";
+const GOVERNANCE_STATE_FILE = "governance-state.json";
+function writeGraphNotices(outputPath, notices) {
+    const absoluteOutputPath = (0, node_path_1.resolve)(outputPath);
+    const noticesPath = (0, node_path_1.resolve)(absoluteOutputPath, NOTICES_FILE_NAME);
+    const content = buildNoticesContent(notices);
+    (0, node_fs_1.mkdirSync)(absoluteOutputPath, { recursive: true });
+    if ((0, node_fs_1.existsSync)(noticesPath)) {
+        const existing = (0, node_fs_1.readFileSync)(noticesPath, "utf-8");
+        if (existing === content) {
+            return;
+        }
+    }
+    (0, node_fs_1.writeFileSync)(noticesPath, content, "utf-8");
+}
+function checkGraphInvalidation(config, repoRoot) {
+    const graphOutputPath = (0, node_path_1.resolve)(repoRoot, config.graph?.outputPath ?? DEFAULT_GRAPH_OUTPUT_PATH);
+    const triggers = config.graph?.invalidationTriggers ?? DEFAULT_INVALIDATION_TRIGGERS;
+    const currentState = {
+        configHash: hashConfig(config),
+        headCommit: resolveHeadCommit(repoRoot),
+    };
+    const previousState = readGovernanceState(graphOutputPath);
+    if (previousState && triggers.includes("config-change") && previousState.configHash !== currentState.configHash) {
+        return { stale: true, reason: "config-change" };
+    }
+    if (previousState && triggers.includes("repo-change") && previousState.headCommit !== currentState.headCommit) {
+        return { stale: true, reason: "repo-change" };
+    }
+    return { stale: false };
+}
+function recordGraphGovernanceState(graphOutputPath, state) {
+    writeGovernanceState(graphOutputPath, state);
+}
+function buildNoticesContent(notices) {
+    const cleaned = [...new Set(notices.map((notice) => notice.trim()).filter((notice) => notice.length > 0))];
+    if (cleaned.length === 0) {
+        return "# NOTICES\n\nNo third-party attributions recorded.\n";
+    }
+    return `# NOTICES\n\n${cleaned.join("\n\n")}\n`;
+}
+function hashConfig(config) {
+    const normalized = stableSerialize(config);
+    return (0, node_crypto_1.createHash)("sha256").update(normalized, "utf-8").digest("hex");
+}
+function stableSerialize(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableSerialize(entry)).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort((a, b) => a.localeCompare(b));
+    const pairs = keys.map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key])}`);
+    return `{${pairs.join(",")}}`;
+}
+function resolveHeadCommit(repoRoot) {
+    return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], {
+        cwd: repoRoot,
+        encoding: "utf-8",
+    }).trim();
+}
+function readGovernanceState(graphOutputPath) {
+    const statePath = (0, node_path_1.resolve)(graphOutputPath, GOVERNANCE_STATE_FILE);
+    if (!(0, node_fs_1.existsSync)(statePath)) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(statePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.configHash !== "string" || typeof parsed.headCommit !== "string") {
+        return null;
+    }
+    return {
+        configHash: parsed.configHash,
+        headCommit: parsed.headCommit,
+    };
+}
+function writeGovernanceState(graphOutputPath, state) {
+    const statePath = (0, node_path_1.resolve)(graphOutputPath, GOVERNANCE_STATE_FILE);
+    (0, node_fs_1.mkdirSync)(graphOutputPath, { recursive: true });
+    (0, node_fs_1.writeFileSync)(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+}

package/dist/graph/parser/extract.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSymbolsFromTree = void 0;
+var extract_js_1 = require("../adapter/typescript-javascript/extract.js");
+Object.defineProperty(exports, "extractSymbolsFromTree", { enumerable: true, get: function () { return extract_js_1.extractTypeScriptJavaScriptSymbolsFromTree; } });

package/dist/graph/parser/loader.js

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