@habitat-ai/service 0.2.0

package/dist/service/modules/catalog/model/policy/check.js

@@ -0,0 +1,207 @@
+const knownRunnerSelectors = new Set(["grit", "habitat", "nx"]);
+/** Selects the closed executable Grit-check and native structure application set. */
+export function selectCheckApplications(catalog, input) {
+    const selectors = input.selectors;
+    const requestedRules = [
+        ...new Set([
+            ...(selectors?.rule === undefined ? [] : [selectors.rule]),
+            ...(selectors?.rules ?? []),
+        ]),
+    ];
+    const hasExplicitSelectors = selectors?.owner !== undefined ||
+        selectors?.instance !== undefined ||
+        selectors?.rule !== undefined ||
+        selectors?.rules !== undefined ||
+        selectors?.runner !== undefined;
+    const issues = [];
+    if (selectors?.owner !== undefined) {
+        const issue = selectionIssue(catalog, "owner", selectors.owner);
+        if (issue !== undefined)
+            issues.push(issue);
+    }
+    if (selectors?.instance !== undefined) {
+        const issue = selectionIssue(catalog, "instance", selectors.instance);
+        if (issue !== undefined)
+            issues.push(issue);
+    }
+    for (const ruleId of requestedRules) {
+        const issue = selectionIssue(catalog, "rule", ruleId);
+        if (issue !== undefined)
+            issues.push(issue);
+    }
+    if (selectors?.runner !== undefined) {
+        const issue = selectionIssue(catalog, "runner", selectors.runner);
+        if (issue !== undefined)
+            issues.push(issue);
+    }
+    if (issues.length > 0)
+        return refused(issues);
+    const selected = catalog.applications.filter((application) => (selectors?.owner === undefined || application.ownerProject === selectors.owner) &&
+        (selectors?.instance === undefined || application.instanceId === selectors.instance) &&
+        (requestedRules.length === 0 || requestedRules.includes(application.ruleId)) &&
+        (selectors?.runner === undefined || application.runner.name === selectors.runner));
+    if (hasExplicitSelectors && selected.length === 0 && !isKnownEmptyRunnerSelection(selectors)) {
+        return refused([
+            issue("selector-empty", "selectors", "The requested selector intersection contains no resolved applications."),
+        ]);
+    }
+    const unsupported = selected.filter(isUnsupportedGritApplication);
+    if (unsupported.length > 0) {
+        return refused(unsupported.map((application) => issue("runner-unsupported", `${application.instanceId}:${application.ruleId}`, `Rule "${application.ruleId}" requires Grit ${application.runner.acquisition.kind}, which catalog.check does not execute.`)));
+    }
+    return {
+        ok: true,
+        applications: selected.filter(isExecutableCheckApplication).sort(compareApplications),
+    };
+}
+/** Extracts the first closed Grit fence from one admitted pattern asset. */
+export function extractGritProgram(contents) {
+    const lines = contents.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+    const opening = lines.findIndex((line) => line === "```grit");
+    if (opening < 0) {
+        return { ok: false, detail: "Pattern asset has no opening ```grit fence." };
+    }
+    const closingOffset = lines.slice(opening + 1).findIndex((line) => line === "```");
+    if (closingOffset < 0) {
+        return { ok: false, detail: "Pattern asset has no closing Grit fence." };
+    }
+    const program = lines.slice(opening + 1, opening + 1 + closingOffset).join("\n");
+    return program.trim().length === 0
+        ? { ok: false, detail: "Pattern asset contains an empty Grit program." }
+        : { ok: true, program };
+}
+/** Produces one semantic report from trusted, repository-relative findings. */
+export function evaluatedApplication(application, findings) {
+    const severity = application.lane === "enforced" ? "error" : "advisory";
+    return {
+        ...applicationIdentity(application),
+        status: findings.length === 0
+            ? "pass"
+            : application.lane === "enforced"
+                ? "fail"
+                : "advisory-findings",
+        disposition: { kind: "evaluated" },
+        findings: findings.map((finding) => ({ ...finding, severity, baselined: false })),
+    };
+}
+/** Produces one deterministic operational-error report for an application. */
+export function failedApplication(application, reason, detail) {
+    return {
+        ...applicationIdentity(application),
+        status: "error",
+        disposition: {
+            kind: "failed",
+            reason,
+            detail: boundedDetail(detail),
+        },
+        findings: [],
+    };
+}
+/** Produces one native Habitat report from pure structure diagnostics. */
+export function evaluatedStructureApplication(application, diagnostics) {
+    const severity = application.lane === "enforced" ? "error" : "advisory";
+    return {
+        ...structureApplicationIdentity(application),
+        status: diagnostics.length === 0
+            ? "pass"
+            : application.lane === "enforced"
+                ? "fail"
+                : "advisory-findings",
+        disposition: { kind: "evaluated" },
+        findings: diagnostics.map((diagnostic) => ({
+            ...diagnostic,
+            severity,
+            baselined: false,
+        })),
+    };
+}
+/** Produces one deterministic native Habitat operational-error report. */
+export function failedStructureApplication(application, reason, detail) {
+    return {
+        ...structureApplicationIdentity(application),
+        status: "error",
+        disposition: { kind: "failed", reason, detail: boundedDetail(detail) },
+        findings: [],
+    };
+}
+/** Completes a check from already ordered application reports. */
+export function completedCheck(applications) {
+    return {
+        _tag: "Completed",
+        ok: applications.every((application) => application.status === "pass" || application.status === "advisory-findings"),
+        applications: [...applications],
+    };
+}
+function applicationIdentity(application) {
+    return {
+        ownerProject: application.ownerProject,
+        instanceId: application.instanceId,
+        ruleId: application.ruleId,
+        runner: "grit",
+        lane: application.lane,
+        locked: false,
+        message: application.message,
+        remediate: application.remediate,
+    };
+}
+function structureApplicationIdentity(application) {
+    return {
+        ownerProject: application.ownerProject,
+        instanceId: application.instanceId,
+        ruleId: application.ruleId,
+        runner: "habitat",
+        lane: application.lane,
+        locked: false,
+        message: application.message,
+        remediate: application.remediate,
+    };
+}
+function isGritCheckApplication(application) {
+    return application.runner.name === "grit" && application.runner.acquisition.kind === "check";
+}
+function isUnsupportedGritApplication(application) {
+    return application.runner.name === "grit" && application.runner.acquisition.kind !== "check";
+}
+function isExecutableCheckApplication(application) {
+    return application.runner.name === "habitat" || isGritCheckApplication(application);
+}
+function compareApplications(left, right) {
+    return (compareText(left.ruleId, right.ruleId) ||
+        compareText(left.instanceId, right.instanceId) ||
+        compareText(left.ownerProject, right.ownerProject));
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function refused(issues) {
+    return { ok: false, issues };
+}
+function issue(code, selector, message) {
+    return { code, selector, message };
+}
+function selectionIssue(catalog, kind, value) {
+    const matches = {
+        owner: catalog.applications.some((application) => application.ownerProject === value),
+        instance: catalog.applications.some((application) => application.instanceId === value),
+        rule: catalog.applications.some((application) => application.ruleId === value),
+        runner: catalog.applications.some((application) => application.runner.name === value),
+    };
+    if (matches[kind] || (kind === "runner" && knownRunnerSelectors.has(value)))
+        return undefined;
+    const actualKind = ["owner", "instance", "rule", "runner"].find((candidate) => candidate !== kind && matches[candidate]);
+    return actualKind === undefined
+        ? issue("selector-unknown", `${kind}:${value}`, `No resolved application uses ${kind} "${value}".`)
+        : issue("selector-wrong-namespace", `${kind}:${value}`, `"${value}" is a known ${actualKind}, not a ${kind}.`);
+}
+function isKnownEmptyRunnerSelection(selectors) {
+    return (selectors?.owner === undefined &&
+        selectors?.instance === undefined &&
+        selectors?.rule === undefined &&
+        selectors?.rules === undefined &&
+        selectors?.runner !== undefined &&
+        knownRunnerSelectors.has(selectors.runner));
+}
+function boundedDetail(detail) {
+    const normalized = detail.trim() || "Application evaluation failed.";
+    return normalized.length <= 4_096 ? normalized : `${normalized.slice(0, 4_093)}...`;
+}

package/dist/service/modules/catalog/model/policy/structure.d.ts

@@ -0,0 +1,64 @@
+import type { SourceInventoryResult } from "@habitat-ai/resource-source-inventory";
+import type { HabitatCatalog } from "../dto/catalog.js";
+import type { StructureCheckFinding } from "../dto/check.js";
+import { type StructureScope } from "../dto/structure.js";
+type RuleApplication = HabitatCatalog["applications"][number];
+/** Resolved application executable by the native Habitat structure policy. */
+export type HabitatStructureApplication = RuleApplication & {
+    readonly runner: Extract<RuleApplication["runner"], {
+        name: "habitat";
+    }>;
+};
+/** Narrows one resolved application to the native structure runner. */
+export declare function isHabitatStructureApplication(application: RuleApplication): application is HabitatStructureApplication;
+/** Live or inventory-derived kind understood by native structure evaluation. */
+export type StructureRootKind = StructureScope["kind"] | "other";
+type BoundStructureScope = Omit<StructureScope, "allowEmpty"> & {
+    readonly allowEmpty: boolean;
+    readonly bindingPath: string;
+};
+/** Schema-admitted structure application with inapplicable unbound scopes removed. */
+export type AdmittedStructureApplication = {
+    readonly application: HabitatStructureApplication;
+    readonly scopes: readonly BoundStructureScope[];
+};
+/** Inventory-derived source universe shared by every application in one invocation. */
+export type StructureUniverse = {
+    readonly paths: readonly string[];
+    readonly trackedNonFilePaths: ReadonlySet<string>;
+    readonly directChildren: ReadonlyMap<string, readonly string[]>;
+};
+type PlannedRoot = {
+    readonly path: string;
+};
+type PlannedScope = {
+    readonly scope: BoundStructureScope;
+    readonly reportPath: string;
+    readonly roots: readonly PlannedRoot[];
+};
+/** Pure inventory interpretation awaiting live matched-root and direct-child observations. */
+export type StructureEvaluationPlan = {
+    readonly application: HabitatStructureApplication;
+    readonly scopes: readonly PlannedScope[];
+    readonly rootObservationPaths: readonly string[];
+    readonly universe: StructureUniverse;
+};
+/** Stable path-only native Habitat diagnostic derived from the public report contract. */
+export type StructureDiagnostic = Pick<StructureCheckFinding, "code" | "path" | "message">;
+/** Admits TypeBox-valid structure authority and resolves its root-role applicability. */
+export declare function admitStructureDocument(value: unknown, application: HabitatStructureApplication): {
+    readonly ok: true;
+    readonly admitted: AdmittedStructureApplication;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/** Derives ancestors and direct children while pruning tracked non-file descendants. */
+export declare function makeStructureUniverse(inventory: SourceInventoryResult): StructureUniverse;
+/** Plans inventory-visible root matching without treating retained Git entries as live facts. */
+export declare function planStructureEvaluation(admitted: AdmittedStructureApplication, universe: StructureUniverse): StructureEvaluationPlan;
+/** Selects inventory-admitted direct children only for roots observed as live directories. */
+export declare function structureChildObservationPaths(plan: StructureEvaluationPlan, observedKinds: ReadonlyMap<string, StructureRootKind | "missing">): readonly string[];
+/** Applies native structure semantics to a prepared source universe and observed root kinds. */
+export declare function evaluateStructurePlan(plan: StructureEvaluationPlan, observedKinds: ReadonlyMap<string, StructureRootKind | "missing">): readonly StructureDiagnostic[];
+export {};

package/dist/service/modules/catalog/model/policy/structure.js

@@ -0,0 +1,249 @@
+import picomatch from "picomatch";
+import { Validator } from "typebox/schema";
+import { STRUCTURE_PICOMATCH_OPTIONS, StructureDocumentSchema, } from "../dto/structure.js";
+/** Narrows one resolved application to the native structure runner. */
+export function isHabitatStructureApplication(application) {
+    return application.runner.name === "habitat";
+}
+const structureValidator = new Validator({}, StructureDocumentSchema);
+/** Admits TypeBox-valid structure authority and resolves its root-role applicability. */
+export function admitStructureDocument(value, application) {
+    if (!structureValidator.Check(value)) {
+        const [, errors] = structureValidator.Errors(value);
+        return {
+            ok: false,
+            detail: errors
+                .slice(0, 20)
+                .map((error) => error.message)
+                .join("; ") || "Structure document does not satisfy schema version 2.",
+        };
+    }
+    const bindings = new Map(application.runner.rootBindings.map((binding) => [
+        binding.rootRole,
+        binding,
+    ]));
+    const unknownRole = value.scopes.find((scope) => !bindings.has(scope.rootRole));
+    if (unknownRole !== undefined) {
+        return {
+            ok: false,
+            detail: `Structure scope "${unknownRole.name}" names unknown root role "${unknownRole.rootRole}".`,
+        };
+    }
+    const scopes = [];
+    for (const scope of value.scopes) {
+        const binding = bindings.get(scope.rootRole);
+        if (binding?.path === undefined)
+            continue;
+        if (appendPath(binding.path, scope.relativePath).length > 4_096) {
+            return {
+                ok: false,
+                detail: `Structure scope "${scope.name}" resolves beyond the maximum repository path length.`,
+            };
+        }
+        scopes.push({ ...scope, allowEmpty: scope.allowEmpty ?? false, bindingPath: binding.path });
+    }
+    return { ok: true, admitted: { application, scopes } };
+}
+/** Derives ancestors and direct children while pruning tracked non-file descendants. */
+export function makeStructureUniverse(inventory) {
+    const trackedNonFilePaths = new Set(inventory.trackedNonFilePaths);
+    const visiblePaths = inventory.paths.filter((candidate) => !ancestors(candidate).some((ancestor) => trackedNonFilePaths.has(ancestor)));
+    const allPaths = new Set([""]);
+    for (const visiblePath of visiblePaths) {
+        allPaths.add(visiblePath);
+        for (const ancestor of ancestors(visiblePath))
+            allPaths.add(ancestor);
+    }
+    const directChildren = new Map();
+    for (const candidate of allPaths) {
+        if (candidate === "")
+            continue;
+        const parent = parentPath(candidate);
+        const children = directChildren.get(parent) ?? [];
+        children.push(baseName(candidate));
+        directChildren.set(parent, children);
+    }
+    for (const children of directChildren.values())
+        children.sort(compareText);
+    return {
+        paths: [...allPaths].sort(compareText),
+        trackedNonFilePaths,
+        directChildren,
+    };
+}
+/** Plans inventory-visible root matching without treating retained Git entries as live facts. */
+export function planStructureEvaluation(admitted, universe) {
+    const rootObservationPaths = new Set();
+    const scopes = admitted.scopes.map((scope) => {
+        const reportPath = appendPath(scope.bindingPath, scope.relativePath);
+        const matches = scope.relativePath === "."
+            ? (candidate) => candidate === ""
+            : picomatch(scope.relativePath, STRUCTURE_PICOMATCH_OPTIONS);
+        const roots = universe.paths
+            .filter((candidate) => {
+            const relativePath = relativeToBoundRoot(candidate, scope.bindingPath);
+            return relativePath !== undefined && matches(relativePath);
+        })
+            .map((candidate) => {
+            rootObservationPaths.add(candidate);
+            return { path: candidate };
+        });
+        return { scope, reportPath, roots };
+    });
+    return {
+        application: admitted.application,
+        scopes,
+        rootObservationPaths: [...rootObservationPaths].sort(compareText),
+        universe,
+    };
+}
+/** Selects inventory-admitted direct children only for roots observed as live directories. */
+export function structureChildObservationPaths(plan, observedKinds) {
+    const paths = new Set();
+    for (const planned of plan.scopes) {
+        if (planned.scope.kind !== "directory")
+            continue;
+        for (const root of planned.roots) {
+            if (plannedStructureKind(plan, root.path, observedKinds) !== "directory")
+                continue;
+            for (const child of plan.universe.directChildren.get(root.path) ?? []) {
+                paths.add(appendPath(root.path, child));
+            }
+        }
+    }
+    return [...paths].sort(compareText);
+}
+/** Applies native structure semantics to a prepared source universe and observed root kinds. */
+export function evaluateStructurePlan(plan, observedKinds) {
+    const diagnostics = [];
+    for (const planned of plan.scopes) {
+        const roots = planned.roots.flatMap((root) => {
+            const observedKind = plannedStructureKind(plan, root.path, observedKinds);
+            return observedKind === "missing" ? [] : [{ path: root.path, kind: observedKind }];
+        });
+        if (!planned.scope.allowEmpty && roots.length === 0) {
+            diagnostics.push({
+                code: "root-missing",
+                path: displayPath(planned.reportPath),
+                message: `Structure scope "${planned.scope.name}" matched no ${planned.scope.kind} roots for ${displayPath(planned.reportPath)}.`,
+            });
+            continue;
+        }
+        for (const root of roots) {
+            if (root.kind === planned.scope.kind)
+                continue;
+            diagnostics.push({
+                code: "wrong-root-kind",
+                path: displayPath(root.path),
+                message: `Structure scope "${planned.scope.name}" expected ${planned.scope.kind} root, but ${displayPath(root.path)} is ${root.kind}.`,
+            });
+        }
+        if (planned.scope.kind !== "directory")
+            continue;
+        for (const root of roots) {
+            if (root.kind !== "directory")
+                continue;
+            const visibleChildren = (plan.universe.directChildren.get(root.path) ?? []).filter((child) => observedStructureKind(appendPath(root.path, child), observedKinds) !== "missing");
+            diagnostics.push(...evaluateDirectoryChildren(planned.scope, root.path, visibleChildren));
+        }
+    }
+    return diagnostics;
+}
+function observedStructureKind(path, observedKinds) {
+    const kind = observedKinds.get(path);
+    if (kind === undefined) {
+        throw new Error(`Missing observation for planned structure path "${path}".`);
+    }
+    return kind;
+}
+function plannedStructureKind(plan, path, observedKinds) {
+    const kind = observedStructureKind(path, observedKinds);
+    return kind !== "missing" && plan.universe.trackedNonFilePaths.has(path) ? "other" : kind;
+}
+function evaluateDirectoryChildren(scope, rootPath, children) {
+    const diagnostics = [];
+    const required = scope.required ?? [];
+    const allowed = scope.allowed ?? [];
+    const forbidden = scope.forbidden ?? [];
+    const requiredMatchers = makeMatchers(required);
+    const allowedMatchers = makeMatchers([...required, ...allowed]);
+    const forbiddenMatchers = makeMatchers(forbidden);
+    for (const pattern of required) {
+        if (children.some((child) => requiredMatchers.get(pattern)?.(child) === true))
+            continue;
+        diagnostics.push({
+            code: "missing-required-child",
+            path: displayPath(rootPath),
+            message: `Structure scope "${scope.name}" requires direct child ${pattern} under ${displayPath(rootPath)}.`,
+        });
+    }
+    for (const child of children) {
+        const forbiddenPattern = firstMatchingPattern(child, forbiddenMatchers);
+        if (forbiddenPattern !== undefined) {
+            diagnostics.push({
+                code: "forbidden-child",
+                path: displayPath(appendPath(rootPath, child)),
+                message: `Structure scope "${scope.name}" forbids direct child ${child} under ${displayPath(rootPath)} via ${forbiddenPattern}.`,
+            });
+            continue;
+        }
+        if (scope.mode === "closed" && firstMatchingPattern(child, allowedMatchers) === undefined) {
+            diagnostics.push({
+                code: "unexpected-child",
+                path: displayPath(appendPath(rootPath, child)),
+                message: `Structure scope "${scope.name}" is closed and does not allow direct child ${child} under ${displayPath(rootPath)}.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+function makeMatchers(patterns) {
+    return new Map(patterns.map((pattern) => [
+        pattern,
+        picomatch(pattern, STRUCTURE_PICOMATCH_OPTIONS),
+    ]));
+}
+function firstMatchingPattern(name, matchers) {
+    for (const [pattern, matches] of matchers) {
+        if (matches(name))
+            return pattern;
+    }
+    return undefined;
+}
+function appendPath(parent, child) {
+    const normalizedParent = parent === "." ? "" : parent;
+    if (child === ".")
+        return normalizedParent;
+    return normalizedParent === "" ? child : `${normalizedParent}/${child}`;
+}
+function relativeToBoundRoot(candidate, bindingPath) {
+    const normalizedBinding = bindingPath === "." ? "" : bindingPath;
+    if (normalizedBinding === "")
+        return candidate;
+    if (candidate === normalizedBinding)
+        return "";
+    const prefix = `${normalizedBinding}/`;
+    return candidate.startsWith(prefix) ? candidate.slice(prefix.length) : undefined;
+}
+function ancestors(candidate) {
+    const parts = candidate.split("/");
+    const out = [];
+    for (let index = 1; index < parts.length; index += 1) {
+        out.push(parts.slice(0, index).join("/"));
+    }
+    return out;
+}
+function parentPath(candidate) {
+    const separator = candidate.lastIndexOf("/");
+    return separator < 0 ? "" : candidate.slice(0, separator);
+}
+function baseName(candidate) {
+    const separator = candidate.lastIndexOf("/");
+    return separator < 0 ? candidate : candidate.slice(separator + 1);
+}
+function displayPath(candidate) {
+    return candidate === "" ? "." : candidate;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}