knodin 0.5.0

package/dist/src/system-config.js

@@ -0,0 +1,615 @@
+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 ? "reckon.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, ".reckon", "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: ".reckon/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 reckon.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 : "reckon.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, "reckon.yaml")));
+    if (team.schemaVersion !== undefined && team.schemaVersion !== 1) {
+        throw new Error("reckon.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;
+}