@habitat-ai/service 0.2.0

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

@@ -0,0 +1,305 @@
+import { RuleEvaluationFailureReasonSchema, RuleEvaluationPositionSchema, } from "@habitat-ai/resource-rule-evaluation";
+import { Type } from "typebox";
+import { CatalogIssueSchema } from "./catalog.js";
+const SelectorValueSchema = Type.String({
+    minLength: 1,
+    maxLength: 250,
+    description: "Non-empty selector value interpreted against resolved applications.",
+});
+const CheckSelectorsSchema = Type.Object({
+    owner: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: 250,
+        description: "Repository project identity whose applications enter the check.",
+    })),
+    instance: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: 250,
+        description: "Exact resolved instance identity whose applications enter the check.",
+    })),
+    rule: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: 200,
+        description: "Single rule identity whose applications enter the check.",
+    })),
+    rules: Type.Optional(Type.Array(SelectorValueSchema, {
+        minItems: 1,
+        uniqueItems: true,
+        description: "Rule identities whose applications enter the check.",
+    })),
+    runner: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: 100,
+        description: "Runner identity whose applications enter the check.",
+    })),
+}, {
+    additionalProperties: false,
+    description: "Optional intersection of resolved-application selectors.",
+});
+/** Closed request for checking the currently resolved Habitat catalog. */
+export const CheckCatalogInputSchema = Type.Object({
+    selectors: Type.Optional(CheckSelectorsSchema),
+}, {
+    additionalProperties: false,
+    description: "Habitat catalog check request.",
+});
+const CheckSelectionIssueCodeSchema = Type.Union([
+    Type.Literal("selector-empty"),
+    Type.Literal("selector-unknown"),
+    Type.Literal("selector-wrong-namespace"),
+    Type.Literal("runner-unsupported"),
+], {
+    description: "Stable semantic reason a requested application selection was refused.",
+});
+const CheckSelectionIssueSchema = Type.Object({
+    code: CheckSelectionIssueCodeSchema,
+    selector: Type.String({
+        minLength: 1,
+        maxLength: 500,
+        description: "Selector or application identity responsible for the refusal.",
+    }),
+    message: Type.String({
+        minLength: 1,
+        maxLength: 8_192,
+        description: "Bounded refusal detail.",
+    }),
+}, {
+    additionalProperties: false,
+    description: "One expected application-selection refusal.",
+});
+const GritCheckFindingSchema = Type.Object({
+    path: Type.String({
+        minLength: 1,
+        maxLength: 4_096,
+        description: "Normalized repository-relative source path.",
+    }),
+    start: RuleEvaluationPositionSchema,
+    end: RuleEvaluationPositionSchema,
+    message: Type.Union([Type.String(), Type.Null()], {
+        description: "Evaluator-authored diagnostic message when one was produced.",
+    }),
+    severity: Type.Union([Type.Literal("error"), Type.Literal("advisory")], {
+        description: "Service-owned severity derived from the application lane.",
+    }),
+    baselined: Type.Literal(false, {
+        description: "Version-three findings are not admitted through the predecessor baseline model.",
+    }),
+}, {
+    additionalProperties: false,
+    description: "One mechanically observed finding with Habitat semantics.",
+});
+const CheckApplicationStatusSchema = Type.Union([
+    Type.Literal("pass"),
+    Type.Literal("fail"),
+    Type.Literal("advisory-findings"),
+    Type.Literal("error"),
+], {
+    description: "Semantic terminal status for one resolved application.",
+});
+const GritCheckApplicationDispositionSchema = Type.Union([
+    Type.Object({
+        kind: Type.Literal("evaluated", {
+            description: "The application completed mechanical evaluation.",
+        }),
+    }, {
+        additionalProperties: false,
+        description: "Completed mechanical evaluation disposition.",
+    }),
+    Type.Object({
+        kind: Type.Literal("failed", {
+            description: "The application could not produce trusted findings.",
+        }),
+        reason: Type.Union([
+            RuleEvaluationFailureReasonSchema,
+            Type.Literal("PatternReadFailed"),
+            Type.Literal("PatternInvalid"),
+            Type.Literal("FindingPathInvalid"),
+        ], {
+            description: "Stable operational failure reason.",
+        }),
+        detail: Type.String({
+            minLength: 1,
+            maxLength: 4_096,
+            description: "Bounded operational failure detail.",
+        }),
+    }, {
+        additionalProperties: false,
+        description: "Failed application evaluation disposition.",
+    }),
+], {
+    description: "Mechanical disposition underlying one semantic application status.",
+});
+const GritCheckApplicationReportSchema = Type.Object({
+    ownerProject: Type.String({
+        minLength: 1,
+        maxLength: 250,
+        description: "Repository project that owns the resolved application.",
+    }),
+    instanceId: Type.String({
+        minLength: 1,
+        maxLength: 250,
+        description: "Repository-unique instance identity.",
+    }),
+    ruleId: Type.String({
+        minLength: 1,
+        maxLength: 200,
+        description: "Resolved rule identity.",
+    }),
+    runner: Type.Literal("grit", {
+        description: "Mechanical runner used by this check operation.",
+    }),
+    lane: Type.Union([Type.Literal("enforced"), Type.Literal("advisory")], {
+        description: "Application policy lane.",
+    }),
+    locked: Type.Literal(false, {
+        description: "Version-three applications do not inherit predecessor baseline locking.",
+    }),
+    status: CheckApplicationStatusSchema,
+    message: Type.String({
+        minLength: 1,
+        maxLength: 8_192,
+        description: "Rule-authored finding message.",
+    }),
+    remediate: Type.Union([Type.String({ maxLength: 16_384 }), Type.Null()], {
+        description: "Rule-authored remediation when supplied.",
+    }),
+    disposition: GritCheckApplicationDispositionSchema,
+    findings: Type.Array(GritCheckFindingSchema, {
+        description: "Deterministically ordered findings for this application.",
+    }),
+}, {
+    additionalProperties: false,
+    description: "One resolved application check report.",
+});
+const StructureFindingCodeSchema = Type.Union([
+    Type.Literal("root-missing"),
+    Type.Literal("wrong-root-kind"),
+    Type.Literal("missing-required-child"),
+    Type.Literal("forbidden-child"),
+    Type.Literal("unexpected-child"),
+], { description: "Stable native Habitat structure diagnostic classification." });
+const StructureCheckFindingSchema = Type.Object({
+    path: Type.String({
+        minLength: 1,
+        maxLength: 4_096,
+        description: "Normalized repository-relative structure path.",
+    }),
+    code: StructureFindingCodeSchema,
+    message: Type.String({
+        minLength: 1,
+        maxLength: 8_192,
+        description: "Deterministic Habitat-authored structure diagnostic.",
+    }),
+    severity: Type.Union([Type.Literal("error"), Type.Literal("advisory")], {
+        description: "Service-owned severity derived from the application lane.",
+    }),
+    baselined: Type.Literal(false, {
+        description: "Version-three findings do not inherit predecessor baselines.",
+    }),
+}, { additionalProperties: false, description: "One path-only native structure finding." });
+const StructureCheckApplicationDispositionSchema = Type.Union([
+    Type.Object({
+        kind: Type.Literal("evaluated", {
+            description: "Native structure evaluation completed.",
+        }),
+    }, { additionalProperties: false, description: "Completed native structure evaluation." }),
+    Type.Object({
+        kind: Type.Literal("failed", {
+            description: "Native structure evaluation failed operationally.",
+        }),
+        reason: Type.Union([
+            Type.Literal("StructureReadFailed"),
+            Type.Literal("StructureInvalid"),
+            Type.Literal("InventoryFailed"),
+            Type.Literal("StructureObservationFailed"),
+        ], { description: "Stable native structure operational failure reason." }),
+        detail: Type.String({
+            minLength: 1,
+            maxLength: 4_096,
+            description: "Bounded native structure failure detail.",
+        }),
+    }, { additionalProperties: false, description: "Failed native structure evaluation." }),
+], { description: "Native structure evaluation disposition." });
+const StructureCheckApplicationReportSchema = Type.Object({
+    ownerProject: Type.String({
+        minLength: 1,
+        maxLength: 250,
+        description: "Repository project that owns this structure application.",
+    }),
+    instanceId: Type.String({
+        minLength: 1,
+        maxLength: 250,
+        description: "Resolved instance evaluated by this structure application.",
+    }),
+    ruleId: Type.String({
+        minLength: 1,
+        maxLength: 200,
+        description: "Native structure rule evaluated for this instance.",
+    }),
+    runner: Type.Literal("habitat", {
+        description: "Native Habitat runner used by this application.",
+    }),
+    lane: Type.Union([Type.Literal("enforced"), Type.Literal("advisory")], {
+        description: "Policy lane that determines finding severity and completion status.",
+    }),
+    locked: Type.Literal(false, {
+        description: "Native structure reports do not expose Grit lock semantics.",
+    }),
+    status: CheckApplicationStatusSchema,
+    message: Type.String({
+        minLength: 1,
+        maxLength: 8_192,
+        description: "Catalog-authored human guidance for this structure rule.",
+    }),
+    remediate: Type.Union([Type.String({ maxLength: 16_384 }), Type.Null()], {
+        description: "Optional catalog-authored remediation guidance.",
+    }),
+    disposition: StructureCheckApplicationDispositionSchema,
+    findings: Type.Array(StructureCheckFindingSchema, {
+        description: "Deterministically ordered path-only structure findings.",
+    }),
+}, { additionalProperties: false, description: "One native Habitat structure report." });
+const CheckApplicationReportSchema = Type.Union([GritCheckApplicationReportSchema, StructureCheckApplicationReportSchema], { description: "Runner-discriminated application check report." });
+/** Closed total result for one current-catalog check. */
+export const CheckCatalogResultSchema = Type.Union([
+    Type.Object({
+        _tag: Type.Literal("CatalogRejected", {
+            description: "Catalog admission failed before application selection.",
+        }),
+        issues: Type.Array(CatalogIssueSchema, {
+            minItems: 1,
+            description: "Catalog issues that prevented checking.",
+        }),
+    }, {
+        additionalProperties: false,
+        description: "Catalog-stage check refusal.",
+    }),
+    Type.Object({
+        _tag: Type.Literal("SelectionRejected", {
+            description: "Application selection failed before mechanical evaluation.",
+        }),
+        issues: Type.Array(CheckSelectionIssueSchema, {
+            minItems: 1,
+            description: "Selection issues that prevented checking.",
+        }),
+    }, {
+        additionalProperties: false,
+        description: "Selection-stage check refusal.",
+    }),
+    Type.Object({
+        _tag: Type.Literal("Completed", {
+            description: "All selected applications reached a semantic terminal status.",
+        }),
+        ok: Type.Boolean({
+            description: "Whether no enforced finding or operational error occurred.",
+        }),
+        applications: Type.Array(CheckApplicationReportSchema, {
+            description: "Application reports in stable rule and instance order.",
+        }),
+    }, {
+        additionalProperties: false,
+        description: "Completed Habitat catalog check.",
+    }),
+], {
+    description: "Catalog refusal, selection refusal, or completed check outcome.",
+});

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

@@ -0,0 +1,23 @@
+import picomatch from "picomatch";
+import { type Static, Type } from "typebox";
+/** Glob options shared by schema admission and native structure evaluation. */
+export declare const STRUCTURE_PICOMATCH_OPTIONS: Readonly<picomatch.PicomatchOptions>;
+/** Sole structural authority for one version-two Habitat structure document. */
+export declare const StructureDocumentSchema: Type.TRefine<Type.TObject<{
+    schemaVersion: Type.TLiteral<2>;
+    scopes: Type.TArray<Type.TObject<{
+        name: Type.TString;
+        rootRole: Type.TString;
+        relativePath: Type.TRefine<Type.TString>;
+        kind: Type.TUnion<[Type.TLiteral<"directory">, Type.TLiteral<"file">]>;
+        mode: Type.TUnion<[Type.TLiteral<"open">, Type.TLiteral<"closed">]>;
+        allowEmpty: Type.TOptional<Type.TBoolean>;
+        required: Type.TOptional<Type.TArray<Type.TRefine<Type.TString>>>;
+        allowed: Type.TOptional<Type.TArray<Type.TRefine<Type.TString>>>;
+        forbidden: Type.TOptional<Type.TArray<Type.TRefine<Type.TString>>>;
+    }>>;
+}>>;
+/** Schema-admitted version-two Habitat structure document. */
+export type StructureDocument = Static<typeof StructureDocumentSchema>;
+/** One schema-admitted structure scope. */
+export type StructureScope = StructureDocument["scopes"][number];

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

@@ -0,0 +1,93 @@
+import picomatch from "picomatch";
+import { Type } from "typebox";
+/** Glob options shared by schema admission and native structure evaluation. */
+export const STRUCTURE_PICOMATCH_OPTIONS = Object.freeze({
+    contains: false,
+    dot: true,
+    strictBrackets: true,
+});
+const RootRoleSchema = Type.String({
+    minLength: 1,
+    maxLength: 200,
+    pattern: "^[a-z0-9][a-z0-9_-]*$",
+    description: "Blueprint root role used as the base for one structure scope.",
+});
+const RootRelativePatternSchema = Type.Refine(Type.String({
+    minLength: 1,
+    maxLength: 4_096,
+    description: "Safe root-relative path or glob selecting structure roots.",
+}), isSafeRootRelativePattern, () => "Expected a safe, valid root-relative path or glob");
+const DirectChildPatternSchema = Type.Refine(Type.String({
+    minLength: 1,
+    maxLength: 1_024,
+    description: "Glob matched against one direct child name.",
+}), isSafeDirectChildPattern, () => "Expected a safe, valid direct-child glob");
+const StructureScopeSchema = Type.Object({
+    name: Type.String({
+        minLength: 1,
+        maxLength: 200,
+        description: "Stable identity for one structure scope.",
+    }),
+    rootRole: RootRoleSchema,
+    relativePath: RootRelativePatternSchema,
+    kind: Type.Union([Type.Literal("directory"), Type.Literal("file")], {
+        description: "Expected kind for every matched scope root.",
+    }),
+    mode: Type.Union([Type.Literal("open"), Type.Literal("closed")], {
+        description: "Whether unmatched direct children are admitted.",
+    }),
+    allowEmpty: Type.Optional(Type.Boolean({ description: "Whether a scope may match no visible roots." })),
+    required: Type.Optional(Type.Array(DirectChildPatternSchema, {
+        uniqueItems: true,
+        description: "Unique direct-child globs that must each match at least one child.",
+    })),
+    allowed: Type.Optional(Type.Array(DirectChildPatternSchema, {
+        uniqueItems: true,
+        description: "Unique direct-child globs admitted by a closed scope.",
+    })),
+    forbidden: Type.Optional(Type.Array(DirectChildPatternSchema, {
+        uniqueItems: true,
+        description: "Unique direct-child globs rejected in every scope mode.",
+    })),
+}, { additionalProperties: false, description: "One closed Habitat structure scope." });
+const StructureDocumentShapeSchema = Type.Object({
+    schemaVersion: Type.Literal(2, { description: "Structure document schema version." }),
+    scopes: Type.Array(StructureScopeSchema, {
+        minItems: 1,
+        description: "Structure scopes evaluated in declared order.",
+    }),
+}, { additionalProperties: false, description: "Closed Habitat structure document." });
+/** Sole structural authority for one version-two Habitat structure document. */
+export const StructureDocumentSchema = Type.Refine(StructureDocumentShapeSchema, hasUniqueScopeNames, () => "Expected unique structure scope names");
+function hasUniqueScopeNames(document) {
+    return new Set(document.scopes.map((scope) => scope.name)).size === document.scopes.length;
+}
+function isSafeRootRelativePattern(value) {
+    if (!isValidGlob(value))
+        return false;
+    if (value === ".")
+        return true;
+    return (!value.startsWith("/") &&
+        !value.endsWith("/") &&
+        !value.includes("\\") &&
+        !/^[A-Za-z]:\//u.test(value) &&
+        !/[\u0000-\u001f\u007f]/u.test(value) &&
+        value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".."));
+}
+function isSafeDirectChildPattern(value) {
+    return (isValidGlob(value) &&
+        value !== "." &&
+        value !== ".." &&
+        !value.includes("/") &&
+        !value.includes("\\") &&
+        !/[\u0000-\u001f\u007f]/u.test(value));
+}
+function isValidGlob(value) {
+    try {
+        picomatch(value, STRUCTURE_PICOMATCH_OPTIONS);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,109 @@
+import type { Path } from "effect";
+import { type BlueprintDefinition, type CatalogIssue, type CompatibilityIndex, type CompatibilityRuleSource, type HabitatInstanceManifest, type PolicyPackManifest, type PolicyPackPackageJson, type ResolveCatalogResult } from "../dto/catalog.js";
+/** One schema-admitted local blueprint source. */
+export type BlueprintSource = {
+    readonly definition: BlueprintDefinition;
+    readonly relativePath: string;
+};
+/** One admitted selected npm policy-pack envelope. */
+export type PolicyPackSource = {
+    readonly name: string;
+    readonly version: string;
+    readonly protocolVersion: 1;
+    readonly blueprints: readonly [];
+};
+/** App-selected absolute package locators interpreted before filesystem I/O. */
+export type PolicyPackSelection = {
+    readonly name: string;
+    readonly packageJsonPath: string;
+    readonly manifestPath: string;
+};
+/** One schema-admitted local instance source. */
+export type InstanceSource = {
+    readonly manifest: HabitatInstanceManifest;
+    readonly relativePath: string;
+};
+/** One schema-admitted inert compatibility rule source. */
+export type CompatibilityRuleDocument = {
+    readonly rule: CompatibilityRuleSource;
+    readonly relativePath: string;
+};
+/** Schema-admitted authority documents observed by the resolve handler. */
+export type CatalogDocuments = {
+    readonly policyPack: PolicyPackSource;
+    readonly blueprints: readonly BlueprintSource[];
+    readonly manifests: readonly InstanceSource[];
+    readonly compatibilityIndex?: CompatibilityIndex;
+    readonly compatibilityRules: readonly CompatibilityRuleDocument[];
+};
+/** Validates the selected policy-pack filesystem locators. */
+export declare function admitPolicyPackSelection(selection: PolicyPackSelection, path: Path.Path): {
+    readonly ok: true;
+    readonly selection: PolicyPackSelection;
+} | {
+    readonly ok: false;
+    readonly issues: readonly CatalogIssue[];
+};
+/** Admits selected package.json identity through the existing TypeBox validator pattern. */
+export declare function admitPolicyPackPackageJson(value: unknown, expectedName: string, sourcePath: string): {
+    readonly ok: true;
+    readonly value: PolicyPackPackageJson;
+} | {
+    readonly ok: false;
+    readonly issues: readonly CatalogIssue[];
+};
+/** Admits the closed protocol envelope and refuses future member activation explicitly. */
+export declare function admitPolicyPackManifest(value: unknown, sourcePath: string): {
+    readonly ok: true;
+    readonly value: PolicyPackManifest;
+} | {
+    readonly ok: false;
+    readonly issues: readonly CatalogIssue[];
+};
+/** Service-observed filesystem facts for one referenced repository path. */
+export type CatalogPathFact = {
+    readonly relativePath: string;
+    readonly absolutePath: string;
+    readonly kind: "directory" | "file" | "missing" | "other";
+    readonly realPath?: string;
+    readonly detail?: string;
+    readonly filesystemError?: boolean;
+};
+/** Admits unknown TOML output as one closed blueprint definition. */
+export declare function admitBlueprintSource(value: unknown, relativePath: string): {
+    readonly ok: true;
+    readonly source: BlueprintSource;
+} | {
+    readonly ok: false;
+    readonly issues: readonly CatalogIssue[];
+};
+/** Admits unknown TOML output as one closed instance manifest. */
+export declare function admitInstanceSource(value: unknown, relativePath: string): {
+    readonly ok: true;
+    readonly source: InstanceSource;
+} | {
+    readonly ok: false;
+    readonly issues: readonly CatalogIssue[];
+};
+/** Admits unknown JSON output as the closed legacy index. */
+export declare function admitCompatibilityIndex(value: unknown, relativePath: string): {
+    readonly ok: true;
+    readonly value: CompatibilityIndex;
+} | {
+    readonly ok: false;
+    readonly issues: readonly CatalogIssue[];
+};
+/** Admits only the inert identity fields required from a legacy rule source. */
+export declare function admitCompatibilityRule(value: unknown, relativePath: string): {
+    readonly ok: true;
+    readonly source: CompatibilityRuleDocument;
+} | {
+    readonly ok: false;
+    readonly issues: readonly CatalogIssue[];
+};
+/** Collects filesystem paths that schema-admitted documents require the service to observe. */
+export declare function referencedRepositoryPaths(documents: CatalogDocuments, path: Path.Path): readonly string[];
+/** Resolves admitted documents and observed paths into the closed public catalog union. */
+export declare function resolveCatalog(documents: CatalogDocuments, pathFacts: ReadonlyMap<string, CatalogPathFact>, workspaceRoot: string, workspaceRealRoot: string, path: Path.Path): ResolveCatalogResult;
+/** Constructs a bounded, sorted rejected result for operational failures. */
+export declare function rejected(issues: readonly CatalogIssue[]): ResolveCatalogResult;