@habitat-ai/resource-source-inventory 0.2.0

package/dist/contract.d.ts

@@ -0,0 +1,50 @@
+import type { Effect } from "effect";
+import { type Static, Type } from "typebox";
+/** Maximum root-path length admitted by one source-inventory observation. */
+export declare const MAX_SOURCE_INVENTORY_ROOT_LENGTH = 16384;
+/** Maximum repository-relative path length admitted by the resource contract. */
+export declare const MAX_SOURCE_INVENTORY_PATH_LENGTH = 4096;
+/** Maximum number of unique visible entry paths admitted by one observation. */
+export declare const MAX_SOURCE_INVENTORY_ENTRIES = 100000;
+/** Maximum diagnostic detail exposed by one source-inventory failure. */
+export declare const MAX_SOURCE_INVENTORY_FAILURE_DETAIL = 4096;
+/** Schema for one canonical, safe, repository-relative visible entry path. */
+export declare const SourceInventoryPathSchema: Type.TRefine<Type.TString>;
+/** Structural schema for one bounded source-inventory observation request. */
+export declare const ObserveSourceInventoryInputSchema: Type.TObject<{
+    root: Type.TReadonly<Type.TString>;
+    maxEntries: Type.TReadonly<Type.TInteger>;
+}>;
+/**
+ * Schema for one canonical visible-entry inventory and its tracked non-file
+ * subset.
+ */
+export declare const SourceInventoryResultSchema: Type.TRefine<Type.TObject<{
+    paths: Type.TReadonly<Type.TImmutable<Type.TArray<Type.TRefine<Type.TString>>>>;
+    trackedNonFilePaths: Type.TReadonly<Type.TImmutable<Type.TArray<Type.TRefine<Type.TString>>>>;
+}>>;
+/** Provider-neutral mechanical reasons an inventory observation can fail. */
+export declare const SourceInventoryFailureReasonSchema: Type.TUnion<[Type.TLiteral<"InvalidInput">, Type.TLiteral<"SetupFailed">, Type.TLiteral<"LimitExceeded">, Type.TLiteral<"CommandFailed">, Type.TLiteral<"InvalidOutput">]>;
+/** Structural schema for one bounded typed source-inventory failure. */
+export declare const SourceInventoryFailureSchema: Type.TObject<{
+    _tag: Type.TReadonly<Type.TLiteral<"SourceInventoryFailure">>;
+    reason: Type.TReadonly<Type.TUnion<[Type.TLiteral<"InvalidInput">, Type.TLiteral<"SetupFailed">, Type.TLiteral<"LimitExceeded">, Type.TLiteral<"CommandFailed">, Type.TLiteral<"InvalidOutput">]>>;
+    path: Type.TReadonly<Type.TOptional<Type.TString>>;
+    detail: Type.TReadonly<Type.TString>;
+}>;
+/** One canonical repository-relative visible entry path. */
+export type SourceInventoryPath = Static<typeof SourceInventoryPathSchema>;
+/** Input for one bounded visible-entry inventory observation. */
+export type ObserveSourceInventoryInput = Static<typeof ObserveSourceInventoryInputSchema>;
+/** Canonical visible entry paths and the tracked non-file subset. */
+export type SourceInventoryResult = Static<typeof SourceInventoryResultSchema>;
+/** One mechanical source-inventory failure reason. */
+export type SourceInventoryFailureReason = Static<typeof SourceInventoryFailureReasonSchema>;
+/** One bounded typed source-inventory failure. */
+export type SourceInventoryFailure = Static<typeof SourceInventoryFailureSchema>;
+/** Checks an unknown value against the complete source-inventory failure contract. */
+export declare function isSourceInventoryFailure(input: unknown): input is SourceInventoryFailure;
+/** Provider-neutral capability for observing one local visible-entry inventory. */
+export interface SourceInventoryResource<R = never> {
+    readonly observe: (input: ObserveSourceInventoryInput) => Effect.Effect<SourceInventoryResult, SourceInventoryFailure, R>;
+}

package/dist/contract.js

@@ -0,0 +1,107 @@
+import { ReadonlyObject, Refine, Type } from "typebox";
+import { Validator } from "typebox/schema";
+/** Maximum root-path length admitted by one source-inventory observation. */
+export const MAX_SOURCE_INVENTORY_ROOT_LENGTH = 16_384;
+/** Maximum repository-relative path length admitted by the resource contract. */
+export const MAX_SOURCE_INVENTORY_PATH_LENGTH = 4_096;
+/** Maximum number of unique visible entry paths admitted by one observation. */
+export const MAX_SOURCE_INVENTORY_ENTRIES = 100_000;
+/** Maximum diagnostic detail exposed by one source-inventory failure. */
+export const MAX_SOURCE_INVENTORY_FAILURE_DETAIL = 4_096;
+const SourceInventoryRootSchema = Type.String({
+    minLength: 1,
+    maxLength: MAX_SOURCE_INVENTORY_ROOT_LENGTH,
+    description: "Caller-selected local source root",
+});
+/** Schema for one canonical, safe, repository-relative visible entry path. */
+export const SourceInventoryPathSchema = Refine(Type.String({
+    minLength: 1,
+    maxLength: MAX_SOURCE_INVENTORY_PATH_LENGTH,
+    description: "Canonical repository-relative visible entry path",
+}), isCanonicalRelativePath, () => "Expected a canonical safe repository-relative path");
+const MaxEntriesSchema = Type.Integer({
+    minimum: 1,
+    maximum: MAX_SOURCE_INVENTORY_ENTRIES,
+    description: "Maximum unique visible entry paths the observation may return",
+});
+/** Structural schema for one bounded source-inventory observation request. */
+export const ObserveSourceInventoryInputSchema = ReadonlyObject(Type.Object({
+    root: SourceInventoryRootSchema,
+    maxEntries: MaxEntriesSchema,
+}), { additionalProperties: false });
+const SourceInventoryPathsSchema = ReadonlyObject(Type.Array(SourceInventoryPathSchema), {
+    maxItems: MAX_SOURCE_INVENTORY_ENTRIES,
+    description: "Unique Git-visible entry paths in canonical order",
+});
+const SourceInventoryResultStructureSchema = ReadonlyObject(Type.Object({
+    paths: SourceInventoryPathsSchema,
+    trackedNonFilePaths: ReadonlyObject(Type.Array(SourceInventoryPathSchema), {
+        maxItems: MAX_SOURCE_INVENTORY_ENTRIES,
+        description: "Tracked symlink and Gitlink entry paths in canonical order",
+    }),
+}), { additionalProperties: false });
+/**
+ * Schema for one canonical visible-entry inventory and its tracked non-file
+ * subset.
+ */
+export const SourceInventoryResultSchema = Refine(SourceInventoryResultStructureSchema, isCanonicalInventory, () => "Expected sorted unique paths and a tracked non-file subset");
+/** Provider-neutral mechanical reasons an inventory observation can fail. */
+export const SourceInventoryFailureReasonSchema = Type.Union([
+    Type.Literal("InvalidInput"),
+    Type.Literal("SetupFailed"),
+    Type.Literal("LimitExceeded"),
+    Type.Literal("CommandFailed"),
+    Type.Literal("InvalidOutput"),
+], {
+    description: "Mechanical reason a source inventory could not be observed",
+});
+/** Structural schema for one bounded typed source-inventory failure. */
+export const SourceInventoryFailureSchema = ReadonlyObject(Type.Object({
+    _tag: Type.Literal("SourceInventoryFailure", {
+        description: "Discriminator for one source-inventory failure",
+    }),
+    reason: SourceInventoryFailureReasonSchema,
+    path: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: MAX_SOURCE_INVENTORY_ROOT_LENGTH,
+        description: "Local source root associated with the failed operation",
+    })),
+    detail: Type.String({
+        minLength: 1,
+        maxLength: MAX_SOURCE_INVENTORY_FAILURE_DETAIL,
+        description: "Bounded operational failure detail",
+    }),
+}), { additionalProperties: false });
+const sourceInventoryFailureValidator = new Validator({}, SourceInventoryFailureSchema);
+/** Checks an unknown value against the complete source-inventory failure contract. */
+export function isSourceInventoryFailure(input) {
+    return sourceInventoryFailureValidator.Check(input);
+}
+function isCanonicalRelativePath(value) {
+    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 isCanonicalInventory(value) {
+    if (!isStrictlySorted(value.paths) || !isStrictlySorted(value.trackedNonFilePaths)) {
+        return false;
+    }
+    const paths = new Set(value.paths);
+    return value.trackedNonFilePaths.every((path) => paths.has(path));
+}
+function isStrictlySorted(paths) {
+    for (let index = 1; index < paths.length; index += 1) {
+        const previous = paths[index - 1];
+        const current = paths[index];
+        if (previous === undefined || current === undefined || compareText(previous, current) >= 0) {
+            return false;
+        }
+    }
+    return true;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/providers/git-effect-platform-node/index.d.ts

@@ -0,0 +1,18 @@
+import type { SourceInventoryResource } from "@habitat-ai/resource-source-inventory";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { type Static, Type } from "typebox";
+type ProviderRequirements = ChildProcessSpawner.ChildProcessSpawner;
+/** Structural schema for local-Git source-inventory provider construction. */
+export declare const GitSourceInventoryProviderOptionsSchema: Type.TObject<{
+    gitExecutable: Type.TReadonly<Type.TOptional<Type.TString>>;
+}>;
+/**
+ * Provider options reserved for focused tests. Production resolution uses the
+ * operator's ordinary `git` command and inherited process configuration.
+ */
+export type GitSourceInventoryProviderOptions = Static<typeof GitSourceInventoryProviderOptionsSchema>;
+/** Creates a local-Git source inventory over Effect child-process services. */
+export declare function makeGitSourceInventoryResource(options?: GitSourceInventoryProviderOptions): SourceInventoryResource<ProviderRequirements>;
+/** Creates a ready Node realization of the local-Git source inventory provider. */
+export declare function makeNodeGitSourceInventoryResource(options?: GitSourceInventoryProviderOptions): SourceInventoryResource<never>;
+export {};

package/dist/providers/git-effect-platform-node/index.js

@@ -0,0 +1,221 @@
+import { NodeServices } from "@effect/platform-node";
+import { MAX_SOURCE_INVENTORY_FAILURE_DETAIL, MAX_SOURCE_INVENTORY_ROOT_LENGTH, ObserveSourceInventoryInputSchema, SourceInventoryPathSchema, SourceInventoryResultSchema, } from "@habitat-ai/resource-source-inventory";
+import { Effect, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ReadonlyObject, Type } from "typebox";
+import { Validator } from "typebox/schema";
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const GIT_INVENTORY_ARGUMENTS = Object.freeze([
+    "ls-files",
+    "--cached",
+    "--others",
+    "--exclude-standard",
+    "--stage",
+    "--abbrev=1",
+    "-t",
+    "-z",
+]);
+const PROCESS_FORCE_KILL_AFTER = "5 seconds";
+const STDERR_LIMIT = 64 * 1_024;
+const STDOUT_LIMIT = 64 * 1_024 * 1_024;
+const TRACKED_RECORD_PATTERN = /^[HSMRCK] (?<mode>100644|100755|120000|160000) [0-9a-f]{1,64} [0-3]\t(?<path>.+)$/su;
+const observeInputValidator = new Validator({}, ObserveSourceInventoryInputSchema);
+const sourcePathValidator = new Validator({}, SourceInventoryPathSchema);
+const sourceInventoryResultValidator = new Validator({}, SourceInventoryResultSchema);
+/** Structural schema for local-Git source-inventory provider construction. */
+export const GitSourceInventoryProviderOptionsSchema = ReadonlyObject(Type.Object({
+    gitExecutable: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: MAX_SOURCE_INVENTORY_ROOT_LENGTH,
+        pattern: "^[^\\u0000]+$",
+        description: "Focused-test override for the ordinary Git executable",
+    })),
+}), { additionalProperties: false });
+const providerOptionsValidator = new Validator({}, GitSourceInventoryProviderOptionsSchema);
+/** Creates a local-Git source inventory over Effect child-process services. */
+export function makeGitSourceInventoryResource(options = {}) {
+    const observe = Effect.fn("sourceInventory.git.observe")(function* (input) {
+        if (!providerOptionsValidator.Check(options)) {
+            return yield* fail("InvalidInput", undefined, "Source-inventory provider options do not match their structural contract");
+        }
+        if (!observeInputValidator.Check(input)) {
+            return yield* fail("InvalidInput", undefined, "Source-inventory input does not match the bounded resource contract");
+        }
+        const gitExecutable = options.gitExecutable ?? "git";
+        const command = yield* runGitInventory(gitExecutable, input.root);
+        if (command.exitCode !== 0) {
+            return yield* fail("CommandFailed", input.root, gitFailureDetail(command.exitCode, command.stderr));
+        }
+        return yield* parseGitInventory(command.stdout, input.root, input.maxEntries);
+    });
+    return Object.freeze({ observe });
+}
+/** Creates a ready Node realization of the local-Git source inventory provider. */
+export function makeNodeGitSourceInventoryResource(options = {}) {
+    const resource = makeGitSourceInventoryResource(options);
+    return Object.freeze({
+        observe: (input) => resource.observe(input).pipe(Effect.provide(NodeServices.layer)),
+    });
+}
+function runGitInventory(executable, root) {
+    const command = ChildProcess.make(executable, GIT_INVENTORY_ARGUMENTS, {
+        cwd: root,
+        extendEnv: true,
+        stdin: "ignore",
+        forceKillAfter: PROCESS_FORCE_KILL_AFTER,
+    });
+    return Effect.scoped(Effect.gen(function* () {
+        const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+        const process = yield* spawner.spawn(command).pipe(mapPlatform(root, "SetupFailed"));
+        const [stdout, stderr, exitCode] = yield* Effect.all([
+            collectBoundedOutput(process.stdout, STDOUT_LIMIT, "stdout", root),
+            collectBoundedOutput(process.stderr, STDERR_LIMIT, "stderr", root),
+            process.exitCode.pipe(mapPlatform(root, "CommandFailed")),
+        ], { concurrency: "unbounded" });
+        return Object.freeze({
+            stdout,
+            stderr,
+            exitCode: Number(exitCode),
+        });
+    }));
+}
+function collectBoundedOutput(stream, maxBytes, output, root) {
+    const initial = Object.freeze({
+        chunks: Object.freeze([]),
+        bytes: 0,
+    });
+    return Stream.runFoldEffect(stream.pipe(Stream.mapError((cause) => platformFailure(root, cause, "CommandFailed"))), () => initial, (state, chunk) => {
+        const bytes = state.bytes + chunk.byteLength;
+        if (bytes > maxBytes) {
+            return fail(output === "stdout" ? "LimitExceeded" : "CommandFailed", root, `Git ${output} exceeds the ${maxBytes}-byte source-inventory bound`);
+        }
+        return Effect.succeed(Object.freeze({
+            chunks: Object.freeze([...state.chunks, chunk]),
+            bytes,
+        }));
+    }).pipe(Effect.map((state) => concatenate(state.chunks, state.bytes)));
+}
+function parseGitInventory(bytes, root, maxEntries) {
+    return decodeGitOutput(bytes, root).pipe(Effect.flatMap((text) => {
+        if (text.length === 0) {
+            return checkedResult(Object.freeze({ paths: Object.freeze([]), trackedNonFilePaths: Object.freeze([]) }), root);
+        }
+        if (!text.endsWith("\0")) {
+            return fail("InvalidOutput", root, "Git inventory output has a truncated NUL record");
+        }
+        const facts = new Map();
+        for (const rawRecord of text.slice(0, -1).split("\0")) {
+            if (rawRecord.length === 0) {
+                return fail("InvalidOutput", root, "Git inventory output contains an empty NUL record");
+            }
+            const record = parseGitRecord(rawRecord);
+            if (record === undefined) {
+                return fail("InvalidOutput", root, "Git ls-files emitted a malformed source-inventory record");
+            }
+            if (!sourcePathValidator.Check(record.path)) {
+                return fail("InvalidOutput", root, "Git ls-files emitted an unsafe or non-canonical relative path");
+            }
+            const existing = facts.get(record.path);
+            if (existing !== undefined) {
+                if (existing.source !== record.source) {
+                    return fail("InvalidOutput", root, "Git ls-files reported one path as both tracked and untracked");
+                }
+                if (existing.source === "tracked" && record.source === "tracked") {
+                    facts.set(record.path, Object.freeze({
+                        source: "tracked",
+                        path: record.path,
+                        trackedNonFile: existing.trackedNonFile || record.trackedNonFile,
+                    }));
+                }
+                continue;
+            }
+            facts.set(record.path, record);
+            if (facts.size > maxEntries) {
+                return fail("LimitExceeded", root, `Git-visible source inventory exceeds maxEntries ${maxEntries}`);
+            }
+        }
+        const paths = Array.from(facts.keys()).sort(compareText);
+        const trackedNonFilePaths = Array.from(facts.values())
+            .flatMap((record) => record.source === "tracked" && record.trackedNonFile ? [record.path] : [])
+            .sort(compareText);
+        return checkedResult(Object.freeze({
+            paths: Object.freeze(paths),
+            trackedNonFilePaths: Object.freeze(trackedNonFilePaths),
+        }), root);
+    }));
+}
+function parseGitRecord(record) {
+    if (record.startsWith("? ")) {
+        const path = normalizeUntrackedPath(record.slice(2));
+        return Object.freeze({ source: "untracked", path });
+    }
+    const match = TRACKED_RECORD_PATTERN.exec(record);
+    const mode = match?.groups?.mode;
+    const path = match?.groups?.path;
+    if (mode === undefined || path === undefined)
+        return undefined;
+    return Object.freeze({
+        source: "tracked",
+        path,
+        trackedNonFile: mode === "120000" || mode === "160000",
+    });
+}
+function normalizeUntrackedPath(path) {
+    return path.endsWith("/") && !path.endsWith("//") ? path.slice(0, -1) : path;
+}
+function checkedResult(result, root) {
+    return sourceInventoryResultValidator.Check(result)
+        ? Effect.succeed(result)
+        : fail("InvalidOutput", root, "Git inventory could not be normalized to the source-inventory contract");
+}
+function decodeGitOutput(bytes, root) {
+    return Effect.try({
+        try: () => decoder.decode(bytes),
+        catch: () => failure("InvalidOutput", root, "Git returned non-UTF-8 source-inventory output"),
+    });
+}
+function gitFailureDetail(exitCode, stderr) {
+    let detail;
+    try {
+        detail = decoder.decode(stderr).trim();
+    }
+    catch {
+        detail = "non-UTF-8 stderr";
+    }
+    return detail.length === 0
+        ? `Git ls-files exited ${exitCode}`
+        : `Git ls-files exited ${exitCode}: ${detail}`;
+}
+function concatenate(chunks, length) {
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function mapPlatform(root, reason) {
+    return (effect) => effect.pipe(Effect.mapError((cause) => platformFailure(root, cause, reason)));
+}
+function platformFailure(root, cause, reason) {
+    return failure(reason, root, cause.message);
+}
+function fail(reason, root, detail) {
+    return Effect.fail(failure(reason, root, detail));
+}
+function failure(reason, root, detail) {
+    const normalized = detail.trim() || "Source-inventory observation failed";
+    const boundedDetail = normalized.length <= MAX_SOURCE_INVENTORY_FAILURE_DETAIL
+        ? normalized
+        : `${normalized.slice(0, MAX_SOURCE_INVENTORY_FAILURE_DETAIL - 3)}...`;
+    return Object.freeze({
+        _tag: "SourceInventoryFailure",
+        reason,
+        ...(root === undefined || root.length === 0 ? {} : { path: root }),
+        detail: boundedDetail,
+    });
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@habitat-ai/resource-source-inventory",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/contract.js",
+  "types": "./dist/contract.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    },
+    "./providers/git-effect-platform-node": {
+      "types": "./dist/providers/git-effect-platform-node/index.d.ts",
+      "default": "./dist/providers/git-effect-platform-node/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test test/contract.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.101",
+    "effect": "4.0.0-beta.101",
+    "typebox": "1.3.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "nx": {
+    "tags": [
+      "type:resource",
+      "layer:resource-contract",
+      "resource:source-inventory"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}