knodin 0.7.5 → 0.7.6

package/dist/src/system-config.js

@@ -1,615 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { parseDocument } from "yaml";
-import { detectDuplicateCandidates, extractRepositoryRelationships, trackedRepositoryFiles, } from "./relationship-adapters.js";
-export const RELATIONSHIP_TYPES = [
-    "depends_on",
-    "provides_api",
-    "consumes_api",
-    "deploys",
-    "provisions",
-    "reads_output",
-    "references_path",
-    "reads_config",
-    "publishes_event",
-    "consumes_event",
-    "uses_image",
-    "generated_from",
-    "vendored_from",
-    "mirror_of",
-    "duplicate_candidate",
-];
-function asRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? value
-        : {};
-}
-function readYaml(filePath) {
-    const document = parseDocument(fs.readFileSync(filePath, "utf-8"), {
-        prettyErrors: true,
-        strict: true,
-        uniqueKeys: true,
-    });
-    if (document.errors.length > 0) {
-        throw new Error(`${filePath}: ${document.errors.map(({ message }) => message).join("; ")}`);
-    }
-    return document.toJS({ maxAliasCount: 25 });
-}
-function optionalYaml(filePath) {
-    try {
-        return readYaml(filePath);
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return {};
-        throw error;
-    }
-}
-function stringValue(value, field) {
-    if (typeof value !== "string" || value.trim() === "")
-        throw new Error(`${field} must be a string`);
-    return value;
-}
-function stableLegacyIdentity(portableReference) {
-    let normalized = portableReference.replaceAll("\\", "/");
-    while (normalized.endsWith("/"))
-        normalized = normalized.slice(0, -1);
-    normalized ||= ".";
-    const basename = path.posix.basename(normalized).replace(/[^a-zA-Z0-9._-]+/g, "-") || "repository";
-    const suffix = crypto.createHash("sha256").update(normalized).digest("hex").slice(0, 10);
-    return `legacy-${basename}-${suffix}`;
-}
-function repositoryRole(value, index) {
-    if (value === undefined)
-        return "source";
-    if (value === "source" || value === "generated" || value === "vendored" || value === "mirrored") {
-        return value;
-    }
-    throw new Error(`repositories[${index}].role is unsupported`);
-}
-function configuredRepository(value, index) {
-    const record = asRecord(value);
-    const role = repositoryRole(record.role, index);
-    const explicitIndex = record.index === "full" || record.index === "provenance-only" ? record.index : undefined;
-    const derived = role === "generated" || role === "vendored" || role === "mirrored";
-    return {
-        id: stringValue(record.id, `repositories[${index}].id`),
-        role,
-        indexMode: explicitIndex ?? (derived ? "provenance-only" : "full"),
-        policySource: explicitIndex ? "knodin.yaml" : "role-default",
-    };
-}
-function configuredSystem(value, systemIndex) {
-    const record = asRecord(value);
-    const components = (Array.isArray(record.components) ? record.components : []).map((component, componentIndex) => {
-        const item = asRecord(component);
-        return {
-            id: stringValue(item.id, `systems[${systemIndex}].components[${componentIndex}].id`),
-            repository: typeof item.repository === "string" ? item.repository : undefined,
-            type: typeof item.type === "string" ? item.type : "component",
-        };
-    });
-    return {
-        id: stringValue(record.id, `systems[${systemIndex}].id`),
-        components,
-    };
-}
-function applyLegacyFederation(repo, repositories, relationships) {
-    const legacyPath = path.join(repo, ".knodin", "federation.json");
-    let legacy;
-    try {
-        legacy = asRecord(JSON.parse(fs.readFileSync(legacyPath, "utf-8")));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return false;
-        throw error;
-    }
-    const peerPaths = Array.isArray(legacy.repos) ? legacy.repos : [];
-    const localRepository = repositories.find(({ path: checkoutPath }) => checkoutPath === repo);
-    const onlyRepository = repositories.length === 1 ? repositories[0] : undefined;
-    const sourceIdentity = localRepository?.id ??
-        (onlyRepository && onlyRepository.path === undefined ? onlyRepository.id : undefined) ??
-        stableLegacyIdentity(".");
-    if (!repositories.some(({ id }) => id === sourceIdentity)) {
-        repositories.push({
-            id: sourceIdentity,
-            role: "source",
-            indexMode: "full",
-            policySource: "role-default",
-            path: repo,
-            pathSource: "legacy-federation",
-        });
-    }
-    let migrated = false;
-    for (const peer of peerPaths) {
-        if (typeof peer !== "string")
-            continue;
-        migrated = true;
-        const checkoutPath = path.resolve(repo, peer);
-        const id = stableLegacyIdentity(peer);
-        if (!repositories.some((repository) => repository.path === checkoutPath)) {
-            repositories.push({
-                id,
-                role: "source",
-                indexMode: "full",
-                policySource: "role-default",
-                path: checkoutPath,
-                pathSource: "legacy-federation",
-            });
-        }
-        relationships.push({
-            type: "depends_on",
-            from: sourceIdentity,
-            to: id,
-            targetIdentity: id,
-            evidence: {
-                location: ".knodin/federation.json",
-                adapter: "legacy-federation",
-                kind: "compatibility",
-                confidence: 1,
-                freshness: "current",
-                indexGeneration: null,
-            },
-        });
-    }
-    return migrated;
-}
-function applyPersonalMappings(repositories, xdgConfigHome) {
-    const personal = asRecord(optionalYaml(path.join(xdgConfigHome, "knodin", "repositories.yaml")));
-    const personalRepositories = asRecord(personal.repositories);
-    for (const repository of repositories) {
-        const checkout = personalRepositories[repository.id];
-        if (typeof checkout !== "string")
-            continue;
-        if (!path.isAbsolute(checkout)) {
-            throw new Error(`personal repository path for ${repository.id} must be absolute; team config keeps paths out of knodin.yaml`);
-        }
-        repository.path = path.normalize(checkout);
-        repository.pathSource = "personal-config";
-    }
-}
-function configuredCheckout(repository, repositories, repo) {
-    if (repository.path)
-        return repository.path;
-    return repositories.length === 1 && repository.id === repositories[0]?.id ? repo : undefined;
-}
-function extractConfiguredRelationships(repositories, repo) {
-    const extractionPaths = new Map(repositories
-        .map((repository) => [configuredCheckout(repository, repositories, repo) ?? "", repository.id])
-        .filter(([checkout]) => checkout !== "" && fs.existsSync(checkout)));
-    return repositories.flatMap((repository) => {
-        const checkout = configuredCheckout(repository, repositories, repo);
-        if (!checkout || !fs.existsSync(checkout))
-            return [];
-        return extractRepositoryRelationships(repository.id, checkout, extractionPaths);
-    });
-}
-function attributeLinePolicyEvidence(line, index) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#"))
-        return [];
-    const [pattern, ...attributes] = trimmed.split(/\s+/);
-    if (!pattern)
-        return [];
-    return attributes.flatMap((attribute) => {
-        if (attribute === "linguist-generated" || attribute === "linguist-generated=true")
-            return [
-                {
-                    category: "generated",
-                    pattern,
-                    location: `.gitattributes:${index + 1}`,
-                    source: "gitattributes",
-                },
-            ];
-        if (attribute === "linguist-vendored" || attribute === "linguist-vendored=true")
-            return [
-                {
-                    category: "vendored",
-                    pattern,
-                    location: `.gitattributes:${index + 1}`,
-                    source: "gitattributes",
-                },
-            ];
-        return [];
-    });
-}
-function attributesPolicyEvidence(checkout) {
-    const evidence = [];
-    const attributesPath = path.join(checkout, ".gitattributes");
-    try {
-        const lines = fs
-            .readFileSync(attributesPath, "utf-8")
-            .slice(0, 1024 * 1024)
-            .split(/\r?\n/);
-        for (const [index, line] of lines.entries())
-            evidence.push(...attributeLinePolicyEvidence(line, index));
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
-    return evidence;
-}
-function metadataPolicyEvidence(file) {
-    const lower = file.toLowerCase();
-    if (!lower.endsWith(".map") &&
-        !/(?:^|\/)(?:bom|sbom)(?:\.[^/]*)?\.json$/.test(lower) &&
-        !lower.endsWith(".intoto.jsonl") &&
-        !lower.includes("provenance"))
-        return undefined;
-    return {
-        category: lower.includes("bom") || lower.endsWith(".intoto.jsonl") || lower.includes("provenance")
-            ? "sbom-slsa"
-            : "build-metadata",
-        pattern: file,
-        location: file,
-        source: "metadata",
-    };
-}
-function generatedHeaderPolicyEvidence(checkout, file) {
-    let descriptor;
-    try {
-        descriptor = fs.openSync(path.join(checkout, file), "r");
-        const buffer = Buffer.alloc(4096);
-        const bytes = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
-        const header = buffer.subarray(0, bytes).toString("utf-8").toLowerCase();
-        if (!header.includes("@generated") &&
-            !header.includes("code generated") &&
-            !header.includes("auto-generated"))
-            return undefined;
-        return {
-            category: "generated",
-            pattern: file,
-            location: `${file}:1`,
-            source: "generated-header",
-        };
-    }
-    catch {
-        // A file removed during the bounded evidence snapshot contributes no signal.
-        return undefined;
-    }
-    finally {
-        if (descriptor !== undefined)
-            fs.closeSync(descriptor);
-    }
-}
-function repositoryPolicyEvidence(checkout) {
-    const evidence = attributesPolicyEvidence(checkout);
-    for (const file of trackedRepositoryFiles(checkout)) {
-        const fileEvidence = metadataPolicyEvidence(file) ?? generatedHeaderPolicyEvidence(checkout, file);
-        if (fileEvidence)
-            evidence.push(fileEvidence);
-    }
-    return evidence;
-}
-function declaredRelationship(value, index) {
-    const record = asRecord(value);
-    const type = stringValue(record.type, `relationships[${index}].type`);
-    if (!RELATIONSHIP_TYPES.includes(type)) {
-        throw new Error(`relationships[${index}].type is unsupported: ${type}`);
-    }
-    const from = stringValue(record.from, `relationships[${index}].from`);
-    const to = stringValue(record.to, `relationships[${index}].to`);
-    const source = asRecord(record.evidence);
-    const confidence = typeof source.confidence === "number" && source.confidence >= 0 && source.confidence <= 1
-        ? source.confidence
-        : 1;
-    return {
-        type: type,
-        from,
-        to,
-        targetIdentity: to,
-        evidence: {
-            location: typeof source.location === "string" && source.location ? source.location : "knodin.yaml",
-            adapter: "knodin-yaml",
-            kind: "declared",
-            confidence,
-            freshness: "current",
-            indexGeneration: null,
-        },
-    };
-}
-export function loadSystemConfiguration(repoPath, options = {}) {
-    const repo = path.resolve(repoPath);
-    const team = asRecord(optionalYaml(path.join(repo, "knodin.yaml")));
-    if (team.schemaVersion !== undefined && team.schemaVersion !== 1) {
-        throw new Error("knodin.yaml: schemaVersion must be 1");
-    }
-    const repositories = (Array.isArray(team.repositories) ? team.repositories : []).map((value, index) => configuredRepository(value, index));
-    const systems = (Array.isArray(team.systems) ? team.systems : []).map((value, index) => configuredSystem(value, index));
-    const relationships = (Array.isArray(team.relationships) ? team.relationships : []).map((value, index) => declaredRelationship(value, index));
-    const xdgConfigHome = options.xdgConfigHome ?? process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
-    applyPersonalMappings(repositories, xdgConfigHome);
-    const legacyFederation = applyLegacyFederation(repo, repositories, relationships);
-    for (const repository of repositories) {
-        const checkout = configuredCheckout(repository, repositories, repo);
-        if (checkout && fs.existsSync(checkout))
-            repository.policyEvidence = repositoryPolicyEvidence(checkout);
-    }
-    relationships.push(...extractConfiguredRelationships(repositories, repo));
-    repositories.sort((left, right) => left.id.localeCompare(right.id));
-    systems.sort((left, right) => left.id.localeCompare(right.id));
-    const uniqueRelationships = [
-        ...new Map(relationships.map((relationship) => [
-            `${relationship.from}\0${relationship.type}\0${relationship.to}\0${relationship.evidence.location}`,
-            relationship,
-        ])).values(),
-    ];
-    uniqueRelationships.sort((left, right) => `${left.from}\0${left.type}\0${left.to}`.localeCompare(`${right.from}\0${right.type}\0${right.to}`));
-    return {
-        schemaVersion: 1,
-        repositories,
-        systems,
-        relationships: uniqueRelationships,
-        compatibility: { legacyFederation },
-    };
-}
-export function validateSystemConfiguration(config) {
-    const issues = [];
-    const repositories = new Set(config.repositories.map(({ id }) => id));
-    for (const system of config.systems)
-        for (const component of system.components)
-            if (component.repository && !repositories.has(component.repository))
-                issues.push({
-                    code: "unresolved-repository",
-                    identity: component.repository,
-                    message: `${system.id}/${component.id} references unknown repository ${component.repository}`,
-                });
-    for (const repository of config.repositories) {
-        if (repository.path && !fs.existsSync(repository.path))
-            issues.push({
-                code: "missing-checkout",
-                identity: repository.id,
-                message: `${repository.id} checkout does not exist at the configured personal path`,
-            });
-    }
-    const componentIds = new Set(config.systems.flatMap(({ components }) => components.map(({ id }) => id)));
-    const knownTargets = new Set([...repositories, ...componentIds]);
-    for (const relationship of config.relationships)
-        issues.push(...validateRelationship(relationship, knownTargets));
-    return { valid: issues.length === 0, requiresPartial: issues.length > 0, issues };
-}
-function validateRelationship(relationship, knownTargets) {
-    const issues = [];
-    const externalPrefixes = [
-        "pkg:",
-        "openapi:",
-        "asyncapi:",
-        "graphql:",
-        "protobuf:",
-        "terraform:",
-        "terraform-state:",
-        "terraform-output:",
-        "oci:",
-        "config:",
-    ];
-    const extractedExternal = relationship.evidence.kind === "extracted" &&
-        externalPrefixes.some((prefix) => relationship.to.startsWith(prefix));
-    if (!knownTargets.has(relationship.from) ||
-        (!knownTargets.has(relationship.to) && !extractedExternal))
-        issues.push({
-            code: "invalid-relationship",
-            identity: `${relationship.from}->${relationship.to}`,
-            message: `${relationship.type} references an unknown source or target identity`,
-        });
-    if (relationship.evidence.confidence < 0.8)
-        issues.push({
-            code: "low-confidence-relationship",
-            identity: `${relationship.from}->${relationship.to}`,
-            message: `${relationship.type} confidence ${relationship.evidence.confidence} is below the system-query threshold`,
-        });
-    if (relationship.evidence.freshness === "stale")
-        issues.push({
-            code: "configuration-drift",
-            identity: `${relationship.from}->${relationship.to}`,
-            message: `${relationship.type} evidence is stale and must be refreshed`,
-        });
-    return issues;
-}
-async function validateComponentHealth(config, component, status, defaultRepositoryPath, existingIssues) {
-    if (!component.repository)
-        return [];
-    const repository = config.repositories.find(({ id }) => id === component.repository);
-    const checkout = repository?.path ?? (config.repositories.length === 1 ? defaultRepositoryPath : undefined);
-    if (!checkout) {
-        if (existingIssues.some(({ identity }) => identity === component.repository))
-            return [];
-        return [
-            {
-                code: "missing-checkout",
-                identity: component.repository,
-                message: `${component.id} has no personal checkout mapping`,
-            },
-        ];
-    }
-    try {
-        const health = await status(checkout);
-        const lifecycleStatus = health.lifecycle?.status;
-        if (health.status === "healthy" && (!lifecycleStatus || lifecycleStatus === "healthy"))
-            return [];
-        const lifecycleDetail = lifecycleStatus && lifecycleStatus !== "healthy"
-            ? ` and lifecycle is ${lifecycleStatus}`
-            : "";
-        return [
-            {
-                code: "unavailable-component",
-                identity: component.id,
-                message: `${component.id} graph is ${health.status}${lifecycleDetail}`,
-            },
-        ];
-    }
-    catch (error) {
-        return [
-            {
-                code: "unavailable-component",
-                identity: component.id,
-                message: `${component.id} health is unknown: ${error instanceof Error ? error.message : String(error)}`,
-            },
-        ];
-    }
-}
-export async function validateSystemHealth(config, systemId, status, defaultRepositoryPath) {
-    const validation = validateSystemConfiguration(config);
-    const issues = [...validation.issues];
-    const system = config.systems.find(({ id }) => id === systemId);
-    if (!system)
-        return validation;
-    for (const component of system.components) {
-        issues.push(...(await validateComponentHealth(config, component, status, defaultRepositoryPath, issues)));
-    }
-    return { valid: issues.length === 0, requiresPartial: issues.length > 0, issues };
-}
-export function queryConfiguredSystem(config, systemId, allowPartial = false, healthValidation) {
-    const system = config.systems.find(({ id }) => id === systemId);
-    if (!system) {
-        return { status: "not-found", systemId, available: config.systems.map(({ id }) => id) };
-    }
-    const validation = healthValidation ?? validateSystemConfiguration(config);
-    if (!validation.valid && !allowPartial) {
-        return {
-            status: "unavailable",
-            systemId,
-            relationships: [],
-            omissions: validation.issues,
-        };
-    }
-    const unavailableRepositories = new Set(validation.issues
-        .filter(({ code }) => code === "unresolved-repository" || code === "missing-checkout")
-        .map(({ identity }) => identity));
-    const omittedComponents = new Set(system.components
-        .filter(({ repository }) => repository !== undefined && unavailableRepositories.has(repository))
-        .map(({ id }) => id));
-    const componentIds = new Set(system.components.map(({ id }) => id));
-    const relationships = config.relationships.filter(({ from, to }) => (componentIds.has(from) || componentIds.has(to)) &&
-        !omittedComponents.has(from) &&
-        !omittedComponents.has(to));
-    return {
-        status: validation.valid ? "ok" : "partial",
-        systemId,
-        relationships,
-        omissions: validation.issues,
-    };
-}
-export function systemMembershipsForPath(config, repositoryPath) {
-    const resolved = path.resolve(repositoryPath);
-    const identities = new Set(config.repositories
-        .filter(({ path: checkout }) => checkout !== undefined && path.resolve(checkout) === resolved)
-        .map(({ id }) => id));
-    if (identities.size === 0 && config.repositories.length === 1 && config.repositories[0])
-        identities.add(config.repositories[0].id);
-    return config.systems
-        .filter(({ components }) => components.some(({ repository }) => repository !== undefined && identities.has(repository)))
-        .map(({ id }) => id)
-        .sort((left, right) => left.localeCompare(right));
-}
-export function indexModeForPath(config, repositoryPath) {
-    const resolved = path.resolve(repositoryPath);
-    const configured = config.repositories.find(({ path: checkout }) => checkout && path.resolve(checkout) === resolved);
-    if (configured)
-        return configured.indexMode;
-    if (config.repositories.length === 1 && config.repositories[0])
-        return config.repositories[0].indexMode;
-    return "full";
-}
-export async function enrichSystemRelationships(config) {
-    const checkouts = config.repositories
-        .filter((repository) => repository.path !== undefined && fs.existsSync(repository.path))
-        .map(({ id, path: checkout }) => ({ id, path: checkout }));
-    if (checkouts.length < 2)
-        return config;
-    const duplicates = await detectDuplicateCandidates(checkouts);
-    if (duplicates.length === 0)
-        return config;
-    return {
-        ...config,
-        relationships: [...config.relationships, ...duplicates].sort((left, right) => `${left.from}\0${left.type}\0${left.to}\0${left.evidence.location}`.localeCompare(`${right.from}\0${right.type}\0${right.to}\0${right.evidence.location}`)),
-    };
-}
-function repositoryForIdentity(config, identity) {
-    if (config.repositories.some(({ id }) => id === identity))
-        return identity;
-    for (const system of config.systems) {
-        const component = system.components.find(({ id }) => id === identity);
-        if (component?.repository)
-            return component.repository;
-    }
-    return undefined;
-}
-function localRepositoryIdentities(config, repositoryPath) {
-    const resolved = path.resolve(repositoryPath);
-    const identities = new Set(config.repositories
-        .filter(({ path: checkout }) => checkout && path.resolve(checkout) === resolved)
-        .map(({ id }) => id));
-    if (identities.size === 0 && config.repositories.length === 1 && config.repositories[0])
-        identities.add(config.repositories[0].id);
-    return identities;
-}
-function crossRepositoryIncoming(config, repositoryPath, target) {
-    const localRepositories = localRepositoryIdentities(config, repositoryPath);
-    const localComponents = new Set(config.systems.flatMap(({ components }) => components
-        .filter(({ repository }) => repository && localRepositories.has(repository))
-        .map(({ id }) => id)));
-    return config.relationships.filter((relationship) => {
-        const sourceRepository = repositoryForIdentity(config, relationship.from);
-        if (!sourceRepository || localRepositories.has(sourceRepository))
-            return false;
-        const targetRepository = repositoryForIdentity(config, relationship.to);
-        return ((targetRepository !== undefined && localRepositories.has(targetRepository)) ||
-            localComponents.has(relationship.to) ||
-            (target === "" && targetRepository === undefined) ||
-            (target !== undefined &&
-                (relationship.to === target || relationship.targetIdentity === target)));
-    });
-}
-/**
- * Conservatively enrich impact/dead-code responses with declared or extracted
- * cross-repository evidence. Only exact, current, high-confidence symbol
- * evidence removes a dead-code candidate. Broader evidence remains a blocker,
- * never proof that an arbitrary symbol is live or safe to delete.
- */
-export function incorporateSystemQueryEvidence(config, repositoryPath, pattern, target, value) {
-    if (!value || typeof value !== "object")
-        return value;
-    const root = value;
-    const incoming = crossRepositoryIncoming(config, repositoryPath, target);
-    if (incoming.length === 0)
-        return value;
-    const evidence = incoming.map((relationship) => ({
-        type: relationship.type,
-        from: relationship.from,
-        to: relationship.to,
-        targetIdentity: relationship.targetIdentity,
-        evidence: relationship.evidence,
-    }));
-    root.crossRepositoryEvidence = {
-        incoming: evidence,
-        interpretation: "Incoming system evidence is source-scoped; non-exact or low-confidence evidence blocks safe-deletion claims.",
-    };
-    if (pattern !== "dead_code" || !Array.isArray(root.results))
-        return root;
-    const rows = root.results;
-    const filtered = rows.flatMap((candidate) => {
-        if (!candidate || typeof candidate !== "object")
-            return [candidate];
-        const row = candidate;
-        const symbol = typeof row.symbol === "string" ? row.symbol : "";
-        const exactLive = incoming.some((relationship) => relationship.evidence.confidence >= 0.8 &&
-            relationship.evidence.freshness === "current" &&
-            (relationship.to === symbol || relationship.targetIdentity === symbol));
-        if (exactLive)
-            return [];
-        return [
-            {
-                ...row,
-                deletionSafe: false,
-                crossRepositoryEvidence: evidence,
-            },
-        ];
-    });
-    root.results = filtered;
-    root.count = filtered.length;
-    return root;
-}