@agent-teams/engineering-foundation 0.5.0 → 0.6.0

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-document-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-document-reader.js","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-document-reader.ts"],"names":[],"mappings":"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"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-filesystem.d.ts

@@ -0,0 +1,14 @@
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
+import { readContainedRegularFile } from "../../../../filesystem-path-safety.js";
+export interface FilesystemMarkdownOperations {
+    readonly lstat: typeof lstat;
+    readonly readContainedRegularFile: typeof readContainedRegularFile;
+    readonly readdir: typeof readdir;
+    readonly realpath: typeof realpath;
+    readonly stat: typeof stat;
+}
+export declare const nodeFilesystemMarkdownOperations: FilesystemMarkdownOperations;
+export declare function isMissingMarkdownFilesystemError(error: unknown): boolean;
+export declare function throwMarkdownFilesystemUnavailable(error: unknown, operation: string): never;
+export declare function markdownPathTraversesSymbolicLink(root: string, candidate: string, filesystem: FilesystemMarkdownOperations, signal?: AbortSignal): Promise<boolean>;
+//# sourceMappingURL=filesystem-markdown-filesystem.d.ts.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-filesystem.d.ts","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-filesystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAIlE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAKjF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAC7B,QAAQ,CAAC,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC;CAC5B;AAED,eAAO,MAAM,gCAAgC,EAAE,4BAM9C,CAAC;AAaF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGxE;AAED,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAa3F;AAED,wBAAsB,iCAAiC,CACrD,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,4BAA4B,EACxC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAsBlB"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-filesystem.js

@@ -0,0 +1,61 @@
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { CapabilityInputError } from "../../../../capability-runtime.js";
+import { readContainedRegularFile } from "../../../../filesystem-path-safety.js";
+import { assertNotCancelled } from "../../../../strict-yaml.js";
+const MISSING_FILESYSTEM_ERROR_CODES = new Set(["ENOENT", "ENOTDIR"]);
+export const nodeFilesystemMarkdownOperations = {
+    lstat,
+    readContainedRegularFile,
+    readdir,
+    realpath,
+    stat
+};
+function filesystemErrorCode(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string")
+        ? error.code
+        : undefined;
+}
+export function isMissingMarkdownFilesystemError(error) {
+    const code = filesystemErrorCode(error);
+    return code !== undefined && MISSING_FILESYSTEM_ERROR_CODES.has(code);
+}
+export function throwMarkdownFilesystemUnavailable(error, operation) {
+    if (error instanceof CapabilityInputError) {
+        throw error;
+    }
+    throw new CapabilityInputError({
+        code: "DOCUMENTATION_FILESYSTEM_UNAVAILABLE",
+        message: `Documentation filesystem is unavailable while ${operation}.`,
+        phase: "documentation-observation",
+        retryable: true
+    }, { cause: error });
+}
+export async function markdownPathTraversesSymbolicLink(root, candidate, filesystem, signal) {
+    const relation = relative(root, candidate);
+    let current = root;
+    for (const segment of relation.split(sep).filter((value) => value.length > 0)) {
+        assertNotCancelled(signal);
+        current = join(current, segment);
+        let metadata;
+        try {
+            metadata = await filesystem.lstat(current);
+        }
+        catch (error) {
+            assertNotCancelled(signal);
+            if (isMissingMarkdownFilesystemError(error)) {
+                return false;
+            }
+            throwMarkdownFilesystemUnavailable(error, "checking Markdown paths for symbolic links");
+        }
+        assertNotCancelled(signal);
+        if (metadata.isSymbolicLink()) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=filesystem-markdown-filesystem.js.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-filesystem.js","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-filesystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,MAAM,8BAA8B,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAUtE,MAAM,CAAC,MAAM,gCAAgC,GAAiC;IAC5E,KAAK;IACL,wBAAwB;IACxB,OAAO;IACP,QAAQ;IACR,IAAI;CACL,CAAC;AAEF,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAC/B;QACC,CAAC,CAAC,KAAK,CAAC,IAAI;QACZ,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAC,KAAc;IAC7D,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,IAAI,KAAK,SAAS,IAAI,8BAA8B,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,kCAAkC,CAAC,KAAc,EAAE,SAAiB;IAClF,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;QAC1C,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,IAAI,oBAAoB,CAC5B;QACE,IAAI,EAAE,sCAAsC;QAC5C,OAAO,EAAE,iDAAiD,SAAS,GAAG;QACtE,KAAK,EAAE,2BAA2B;QAClC,SAAS,EAAE,IAAI;KAChB,EACD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,IAAY,EACZ,SAAiB,EACjB,UAAwC,EACxC,MAAoB;IAEpB,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC3C,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC9E,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,QAAQ,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,kBAAkB,CAAC,MAAM,CAAC,CAAC;YAC3B,IAAI,gCAAgC,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5C,OAAO,KAAK,CAAC;YACf,CAAC;YACD,kCAAkC,CAAC,KAAK,EAAE,4CAA4C,CAAC,CAAC;QAC1F,CAAC;QACD,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-paths.d.ts

@@ -0,0 +1,8 @@
+import { type FilesystemMarkdownOperations } from "./filesystem-markdown-filesystem.js";
+export interface FilesystemMarkdownRepositoryContext {
+    readonly canonicalRoot: string;
+}
+export declare function createFilesystemMarkdownRepositoryContext(consumerRoot: string, filesystem?: FilesystemMarkdownOperations, signal?: AbortSignal): Promise<FilesystemMarkdownRepositoryContext>;
+export declare function markdownRepositoryPath(root: string, absolutePath: string): string;
+export declare function isWithinMarkdownRepository(root: string, candidate: string): boolean;
+//# sourceMappingURL=filesystem-markdown-paths.d.ts.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-paths.d.ts","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-paths.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,4BAA4B,EAClC,MAAM,qCAAqC,CAAC;AAE7C,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,wBAAsB,yCAAyC,CAC7D,YAAY,EAAE,MAAM,EACpB,UAAU,GAAE,4BAA+D,EAC3E,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,mCAAmC,CAAC,CAiC9C;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,MAAM,CAER;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAGT"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-paths.js

@@ -0,0 +1,44 @@
+import { isAbsolute, relative, sep } from "node:path";
+import { CapabilityInputError } from "../../../../capability-runtime.js";
+import { assertNotCancelled } from "../../../../strict-yaml.js";
+import { isMissingMarkdownFilesystemError, nodeFilesystemMarkdownOperations, throwMarkdownFilesystemUnavailable } from "./filesystem-markdown-filesystem.js";
+export async function createFilesystemMarkdownRepositoryContext(consumerRoot, filesystem = nodeFilesystemMarkdownOperations, signal) {
+    assertNotCancelled(signal);
+    let canonicalRoot;
+    let metadata;
+    try {
+        canonicalRoot = await filesystem.realpath(consumerRoot);
+        assertNotCancelled(signal);
+        metadata = await filesystem.stat(canonicalRoot);
+    }
+    catch (error) {
+        assertNotCancelled(signal);
+        if (isMissingMarkdownFilesystemError(error)) {
+            throw new CapabilityInputError({
+                code: "DOCUMENTATION_CONSUMER_ROOT_MISSING",
+                message: "Consumer root must be an existing directory.",
+                phase: "documentation-observation",
+                retryable: false
+            }, { cause: error });
+        }
+        throwMarkdownFilesystemUnavailable(error, "accessing the consumer root");
+    }
+    assertNotCancelled(signal);
+    if (!metadata.isDirectory()) {
+        throw new CapabilityInputError({
+            code: "DOCUMENTATION_CONSUMER_ROOT_INVALID",
+            message: "Consumer root must be a directory.",
+            phase: "documentation-observation",
+            retryable: false
+        });
+    }
+    return { canonicalRoot };
+}
+export function markdownRepositoryPath(root, absolutePath) {
+    return relative(root, absolutePath).split(sep).join("/");
+}
+export function isWithinMarkdownRepository(root, candidate) {
+    const relation = relative(root, candidate);
+    return relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation);
+}
+//# sourceMappingURL=filesystem-markdown-paths.js.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-paths.js","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EACL,gCAAgC,EAChC,gCAAgC,EAChC,kCAAkC,EAEnC,MAAM,qCAAqC,CAAC;AAM7C,MAAM,CAAC,KAAK,UAAU,yCAAyC,CAC7D,YAAoB,EACpB,UAAU,GAAiC,gCAAgC,EAC3E,MAAoB;IAEpB,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,aAAqB,CAAC;IAC1B,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,aAAa,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QACxD,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,QAAQ,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,gCAAgC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,oBAAoB,CAC5B;gBACE,IAAI,EAAE,qCAAqC;gBAC3C,OAAO,EAAE,8CAA8C;gBACvD,KAAK,EAAE,2BAA2B;gBAClC,SAAS,EAAE,KAAK;aACjB,EACD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QACD,kCAAkC,CAAC,KAAK,EAAE,6BAA6B,CAAC,CAAC;IAC3E,CAAC;IACD,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,oBAAoB,CAAC;YAC7B,IAAI,EAAE,qCAAqC;YAC3C,OAAO,EAAE,oCAAoC;YAC7C,KAAK,EAAE,2BAA2B;YAClC,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,aAAa,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,YAAoB;IAEpB,OAAO,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,IAAY,EACZ,SAAiB;IAEjB,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC3C,OAAO,QAAQ,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AACxF,CAAC"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-reference-resolver.d.ts

@@ -0,0 +1,6 @@
+import type { MarkdownReferenceResolution } from "../../../application/model/markdown-document.js";
+import type { ResolveMarkdownReferenceRequest } from "../../../application/ports/markdown-repository.js";
+import { FilesystemMarkdownDocumentReader } from "./filesystem-markdown-document-reader.js";
+import { type FilesystemMarkdownOperations } from "./filesystem-markdown-filesystem.js";
+export declare function resolveFilesystemMarkdownReference(request: ResolveMarkdownReferenceRequest, reader: FilesystemMarkdownDocumentReader, filesystem?: FilesystemMarkdownOperations): Promise<MarkdownReferenceResolution>;
+//# sourceMappingURL=filesystem-markdown-reference-resolver.d.ts.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-reference-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-reference-resolver.d.ts","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-reference-resolver.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iDAAiD,CAAC;AACnG,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,mDAAmD,CAAC;AACzG,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAC5F,OAAO,EAKL,KAAK,4BAA4B,EAClC,MAAM,qCAAqC,CAAC;AAkN7C,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,+BAA+B,EACxC,MAAM,EAAE,gCAAgC,EACxC,UAAU,GAAE,4BAA+D,GAC1E,OAAO,CAAC,2BAA2B,CAAC,CA2CtC"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-reference-resolver.js

@@ -0,0 +1,160 @@
+import { extname, resolve } from "node:path";
+import { assertNotCancelled } from "../../../../strict-yaml.js";
+import { FilesystemMarkdownDocumentReader } from "./filesystem-markdown-document-reader.js";
+import { isMissingMarkdownFilesystemError, markdownPathTraversesSymbolicLink, nodeFilesystemMarkdownOperations, throwMarkdownFilesystemUnavailable } from "./filesystem-markdown-filesystem.js";
+import { createFilesystemMarkdownRepositoryContext, isWithinMarkdownRepository, markdownRepositoryPath } from "./filesystem-markdown-paths.js";
+import { parseMarkdownReferenceTarget, stripMarkdownReferenceQuery } from "./markdown-reference-target.js";
+async function hasExactFilesystemSpelling(absolutePath, filesystem, signal) {
+    try {
+        const canonicalPath = await filesystem.realpath(absolutePath);
+        assertNotCancelled(signal);
+        return canonicalPath === absolutePath;
+    }
+    catch (error) {
+        assertNotCancelled(signal);
+        if (isMissingMarkdownFilesystemError(error)) {
+            return false;
+        }
+        throwMarkdownFilesystemUnavailable(error, "checking Markdown reference path spelling");
+    }
+}
+function terminalTargetResolution(target) {
+    if (target.kind === "external") {
+        return { kind: "external" };
+    }
+    if (target.kind === "unsafe") {
+        return { kind: "unsafe", reason: target.reason };
+    }
+    return undefined;
+}
+async function resolveLocalCandidate(context, sourceRepositoryPath, target, filesystem, signal) {
+    assertNotCancelled(signal);
+    const sourcePath = resolve(context.canonicalRoot, sourceRepositoryPath);
+    const candidate = target.length === 0
+        ? sourcePath
+        : resolve(sourcePath, "..", stripMarkdownReferenceQuery(target));
+    if (!isWithinMarkdownRepository(context.canonicalRoot, candidate)) {
+        return { kind: "unsafe", reason: "repository-escape" };
+    }
+    if (await markdownPathTraversesSymbolicLink(context.canonicalRoot, candidate, filesystem, signal)) {
+        return { kind: "unsafe", reason: "symbolic-link" };
+    }
+    return { absolutePath: candidate, kind: "candidate" };
+}
+async function inspectFileTarget(context, absolutePath, missingReason, filesystem, signal) {
+    let metadata;
+    try {
+        metadata = await filesystem.lstat(absolutePath);
+    }
+    catch (error) {
+        assertNotCancelled(signal);
+        if (isMissingMarkdownFilesystemError(error)) {
+            return {
+                kind: "missing",
+                reason: missingReason,
+                repositoryPath: markdownRepositoryPath(context.canonicalRoot, absolutePath)
+            };
+        }
+        throwMarkdownFilesystemUnavailable(error, "inspecting a Markdown reference target");
+    }
+    assertNotCancelled(signal);
+    if (metadata.isSymbolicLink()) {
+        return { kind: "unsafe", reason: "symbolic-link" };
+    }
+    if (!metadata.isFile()) {
+        return {
+            kind: "missing",
+            reason: "target-missing",
+            repositoryPath: markdownRepositoryPath(context.canonicalRoot, absolutePath)
+        };
+    }
+    if (!(await hasExactFilesystemSpelling(absolutePath, filesystem, signal))) {
+        return {
+            kind: "missing",
+            reason: missingReason,
+            repositoryPath: markdownRepositoryPath(context.canonicalRoot, absolutePath)
+        };
+    }
+    return { absolutePath, kind: "located" };
+}
+async function locateReferenceTarget(context, candidate, filesystem, signal) {
+    let metadata;
+    try {
+        metadata = await filesystem.lstat(candidate);
+    }
+    catch (error) {
+        assertNotCancelled(signal);
+        if (isMissingMarkdownFilesystemError(error)) {
+            return {
+                kind: "missing",
+                reason: "target-missing",
+                repositoryPath: markdownRepositoryPath(context.canonicalRoot, candidate)
+            };
+        }
+        throwMarkdownFilesystemUnavailable(error, "inspecting a Markdown reference target");
+    }
+    assertNotCancelled(signal);
+    if (metadata.isSymbolicLink()) {
+        return { kind: "unsafe", reason: "symbolic-link" };
+    }
+    if (!(await hasExactFilesystemSpelling(candidate, filesystem, signal))) {
+        return {
+            kind: "missing",
+            reason: "target-missing",
+            repositoryPath: markdownRepositoryPath(context.canonicalRoot, candidate)
+        };
+    }
+    if (!metadata.isDirectory()) {
+        return metadata.isFile()
+            ? { absolutePath: candidate, kind: "located" }
+            : {
+                kind: "missing",
+                reason: "target-missing",
+                repositoryPath: markdownRepositoryPath(context.canonicalRoot, candidate)
+            };
+    }
+    const readmePath = resolve(candidate, "README.md");
+    if (await markdownPathTraversesSymbolicLink(context.canonicalRoot, readmePath, filesystem, signal)) {
+        return { kind: "unsafe", reason: "symbolic-link" };
+    }
+    return inspectFileTarget(context, readmePath, "directory-readme-missing", filesystem, signal);
+}
+async function resolveLocatedTarget(context, target, fragment, reader, signal) {
+    const repositoryPath = markdownRepositoryPath(context.canonicalRoot, target.absolutePath);
+    if (extname(target.absolutePath).toLowerCase() !== ".md") {
+        return { fragment, kind: "file", repositoryPath };
+    }
+    const document = await reader.read(context, target.absolutePath, signal);
+    if (document === undefined) {
+        return { kind: "missing", reason: "target-missing", repositoryPath };
+    }
+    return {
+        fragment,
+        kind: "file",
+        markdownDocument: document,
+        repositoryPath
+    };
+}
+export async function resolveFilesystemMarkdownReference(request, reader, filesystem = nodeFilesystemMarkdownOperations) {
+    assertNotCancelled(request.signal);
+    const context = await createFilesystemMarkdownRepositoryContext(request.consumerRoot, filesystem, request.signal);
+    assertNotCancelled(request.signal);
+    const target = parseMarkdownReferenceTarget(request.rawTarget);
+    const terminal = terminalTargetResolution(target);
+    if (terminal !== undefined) {
+        return terminal;
+    }
+    if (target.kind !== "local") {
+        throw new Error("Markdown reference target classification is incomplete.");
+    }
+    const candidate = await resolveLocalCandidate(context, request.source.repositoryPath, target.target, filesystem, request.signal);
+    if (candidate.kind !== "candidate") {
+        return candidate;
+    }
+    const locatedTarget = await locateReferenceTarget(context, candidate.absolutePath, filesystem, request.signal);
+    if (locatedTarget.kind !== "located") {
+        return locatedTarget;
+    }
+    return resolveLocatedTarget(context, locatedTarget, target.fragment, reader, request.signal);
+}
+//# sourceMappingURL=filesystem-markdown-reference-resolver.js.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-reference-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-reference-resolver.js","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-reference-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGhE,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAC5F,OAAO,EACL,gCAAgC,EAChC,iCAAiC,EACjC,gCAAgC,EAChC,kCAAkC,EAEnC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,yCAAyC,EACzC,0BAA0B,EAC1B,sBAAsB,EAEvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAE5B,MAAM,gCAAgC,CAAC;AAexC,KAAK,UAAU,0BAA0B,CACvC,YAAoB,EACpB,UAAwC,EACxC,MAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAC9D,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,aAAa,KAAK,YAAY,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,gCAAgC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,OAAO,KAAK,CAAC;QACf,CAAC;QACD,kCAAkC,CAAC,KAAK,EAAE,2CAA2C,CAAC,CAAC;IACzF,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB,CAC/B,MAA+B;IAE/B,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,OAA4C,EAC5C,oBAA4B,EAC5B,MAAc,EACd,UAAwC,EACxC,MAAoB;IAEpB,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC;QACnC,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,IAAI,CAAC,0BAA0B,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,EAAE,CAAC;QAClE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACzD,CAAC;IACD,IACE,MAAM,iCAAiC,CACrC,OAAO,CAAC,aAAa,EACrB,SAAS,EACT,UAAU,EACV,MAAM,CACP,EACD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AACxD,CAAC;AAED,KAAK,UAAU,iBAAiB,CAC9B,OAA4C,EAC5C,YAAoB,EACpB,aAA4D,EAC5D,UAAwC,EACxC,MAAoB;IAEpB,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,gCAAgC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,aAAa;gBACrB,cAAc,EAAE,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,YAAY,CAAC;aAC5E,CAAC;QACJ,CAAC;QACD,kCAAkC,CAAC,KAAK,EAAE,wCAAwC,CAAC,CAAC;IACtF,CAAC;IACD,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QACvB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,gBAAgB;YACxB,cAAc,EAAE,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,YAAY,CAAC;SAC5E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,0BAA0B,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;QAC1E,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,aAAa;YACrB,cAAc,EAAE,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,YAAY,CAAC;SAC5E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC3C,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,OAA4C,EAC5C,SAAiB,EACjB,UAAwC,EACxC,MAAoB;IAEpB,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,gCAAgC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,gBAAgB;gBACxB,cAAc,EAAE,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC;aACzE,CAAC;QACJ,CAAC;QACD,kCAAkC,CAAC,KAAK,EAAE,wCAAwC,CAAC,CAAC;IACtF,CAAC;IACD,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,0BAA0B,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,gBAAgB;YACxB,cAAc,EAAE,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC;SACzE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,MAAM,EAAE;YACtB,CAAC,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YAC9C,CAAC,CAAC;gBACE,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,gBAAgB;gBACxB,cAAc,EAAE,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC;aACzE,CAAC;IACR,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD,IACE,MAAM,iCAAiC,CACrC,OAAO,CAAC,aAAa,EACrB,UAAU,EACV,UAAU,EACV,MAAM,CACP,EACD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,iBAAiB,CACtB,OAAO,EACP,UAAU,EACV,0BAA0B,EAC1B,UAAU,EACV,MAAM,CACP,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,oBAAoB,CACjC,OAA4C,EAC5C,MAA8B,EAC9B,QAAgB,EAChB,MAAwC,EACxC,MAAoB;IAEpB,MAAM,cAAc,GAAG,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC1F,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK,EAAE,CAAC;QACzD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACpD,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACzE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACvE,CAAC;IACD,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,MAAM;QACZ,gBAAgB,EAAE,QAAQ;QAC1B,cAAc;KACf,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,OAAwC,EACxC,MAAwC,EACxC,UAAU,GAAiC,gCAAgC;IAE3E,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,MAAM,yCAAyC,CAC7D,OAAO,CAAC,YAAY,EACpB,UAAU,EACV,OAAO,CAAC,MAAM,CACf,CAAC;IACF,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,4BAA4B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,qBAAqB,CAC3C,OAAO,EACP,OAAO,CAAC,MAAM,CAAC,cAAc,EAC7B,MAAM,CAAC,MAAM,EACb,UAAU,EACV,OAAO,CAAC,MAAM,CACf,CAAC;IACF,IAAI,SAAS,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACnC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,aAAa,GAAG,MAAM,qBAAqB,CAC/C,OAAO,EACP,SAAS,CAAC,YAAY,EACtB,UAAU,EACV,OAAO,CAAC,MAAM,CACf,CAAC;IACF,IAAI,aAAa,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,OAAO,oBAAoB,CACzB,OAAO,EACP,aAAa,EACb,MAAM,CAAC,QAAQ,EACf,MAAM,EACN,OAAO,CAAC,MAAM,CACf,CAAC;AACJ,CAAC"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-repository.d.ts

@@ -0,0 +1,8 @@
+import type { MarkdownRepositoryObservation, MarkdownReferenceResolution } from "../../../application/model/markdown-document.js";
+import type { MarkdownRepository, ObserveMarkdownRepositoryRequest, ResolveMarkdownReferenceRequest } from "../../../application/ports/markdown-repository.js";
+export declare class FilesystemMarkdownRepository implements MarkdownRepository {
+    #private;
+    observe(request: ObserveMarkdownRepositoryRequest): Promise<MarkdownRepositoryObservation>;
+    resolveReference(request: ResolveMarkdownReferenceRequest): Promise<MarkdownReferenceResolution>;
+}
+//# sourceMappingURL=filesystem-markdown-repository.d.ts.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-repository.d.ts","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-repository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAC7B,2BAA2B,EAC5B,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EACV,kBAAkB,EAClB,gCAAgC,EAChC,+BAA+B,EAChC,MAAM,mDAAmD,CAAC;AAK3D,qBAAa,4BAA6B,YAAW,kBAAkB;;IAG/D,OAAO,CACX,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,6BAA6B,CAAC,CAExC;IAEK,gBAAgB,CACpB,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,2BAA2B,CAAC,CAEtC;CACF"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-repository.js

@@ -0,0 +1,13 @@
+import { FilesystemMarkdownDocumentReader } from "./filesystem-markdown-document-reader.js";
+import { resolveFilesystemMarkdownReference } from "./filesystem-markdown-reference-resolver.js";
+import { observeFilesystemMarkdownTree } from "./filesystem-markdown-tree-observer.js";
+export class FilesystemMarkdownRepository {
+    #documentReader = new FilesystemMarkdownDocumentReader();
+    async observe(request) {
+        return observeFilesystemMarkdownTree(request, this.#documentReader);
+    }
+    async resolveReference(request) {
+        return resolveFilesystemMarkdownReference(request, this.#documentReader);
+    }
+}
+//# sourceMappingURL=filesystem-markdown-repository.js.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-repository.js","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-repository.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAC5F,OAAO,EAAE,kCAAkC,EAAE,MAAM,6CAA6C,CAAC;AACjG,OAAO,EAAE,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AAEvF,MAAM,OAAO,4BAA4B;IAC9B,eAAe,GAAG,IAAI,gCAAgC,EAAE,CAAC;IAElE,KAAK,CAAC,OAAO,CACX,OAAyC;QAEzC,OAAO,6BAA6B,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,gBAAgB,CACpB,OAAwC;QAExC,OAAO,kCAAkC,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IAC3E,CAAC;CACF"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-tree-observer.d.ts

@@ -0,0 +1,6 @@
+import type { MarkdownRepositoryObservation } from "../../../application/model/markdown-document.js";
+import type { ObserveMarkdownRepositoryRequest } from "../../../application/ports/markdown-repository.js";
+import { FilesystemMarkdownDocumentReader } from "./filesystem-markdown-document-reader.js";
+import { type FilesystemMarkdownOperations } from "./filesystem-markdown-filesystem.js";
+export declare function observeFilesystemMarkdownTree(request: ObserveMarkdownRepositoryRequest, reader: FilesystemMarkdownDocumentReader, filesystem?: FilesystemMarkdownOperations): Promise<MarkdownRepositoryObservation>;
+//# sourceMappingURL=filesystem-markdown-tree-observer.d.ts.map

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-tree-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-markdown-tree-observer.d.ts","sourceRoot":"","sources":["../../../../../src/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-tree-observer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,6BAA6B,EAC9B,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,mDAAmD,CAAC;AAC1G,OAAO,EACL,gCAAgC,EAEjC,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAKL,KAAK,4BAA4B,EAClC,MAAM,qCAAqC,CAAC;AAwR7C,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,gCAAgC,EACzC,MAAM,EAAE,gCAAgC,EACxC,UAAU,GAAE,4BAA+D,GAC1E,OAAO,CAAC,6BAA6B,CAAC,CAqCxC"}

package/dist/documentation-observation/adapters/outbound/filesystem/filesystem-markdown-tree-observer.js

@@ -0,0 +1,233 @@
+import { extname, resolve } from "node:path";
+import { compareBinaryStrings } from "../../../../binary-string-comparator.js";
+import { CapabilityInputError } from "../../../../capability-runtime.js";
+import { assertNotCancelled } from "../../../../strict-yaml.js";
+import { FilesystemMarkdownDocumentReader, MAX_MARKDOWN_BYTES } from "./filesystem-markdown-document-reader.js";
+import { isMissingMarkdownFilesystemError, markdownPathTraversesSymbolicLink, nodeFilesystemMarkdownOperations, throwMarkdownFilesystemUnavailable } from "./filesystem-markdown-filesystem.js";
+import { createFilesystemMarkdownRepositoryContext, isWithinMarkdownRepository, markdownRepositoryPath } from "./filesystem-markdown-paths.js";
+const SKIPPED_DIRECTORY_NAMES = new Set([".git", "node_modules"]);
+const MAX_MARKDOWN_DOCUMENTS = 10_000;
+const MAX_MARKDOWN_ISSUES = 10_000;
+const MAX_MARKDOWN_REFERENCES = 100_000;
+const MAX_MARKDOWN_TOTAL_BYTES = 32 * 1024 * 1024;
+function resourceLimit(message) {
+    throw new CapabilityInputError({
+        code: "DOCUMENTATION_RESOURCE_LIMIT_EXCEEDED",
+        message,
+        phase: "documentation-observation",
+        retryable: false
+    });
+}
+function addIssue(collector, issue) {
+    if (collector.issues.length >= MAX_MARKDOWN_ISSUES) {
+        resourceLimit(`Markdown observation exceeds ${MAX_MARKDOWN_ISSUES} issues.`);
+    }
+    collector.issues.push(issue);
+}
+async function walkConfiguredRoot(walk, root) {
+    const { collector, filesystem, repository: context, signal } = walk;
+    const absoluteRoot = resolve(context.canonicalRoot, root);
+    if (!isWithinMarkdownRepository(context.canonicalRoot, absoluteRoot)) {
+        addIssue(collector, {
+            kind: "symbolic-link",
+            message: "Configured Markdown root escapes the consumer repository.",
+            repositoryPath: root
+        });
+        return;
+    }
+    if (await markdownPathTraversesSymbolicLink(context.canonicalRoot, absoluteRoot, filesystem, signal)) {
+        addIssue(collector, {
+            kind: "symbolic-link",
+            message: "Configured Markdown root traverses a symbolic link.",
+            repositoryPath: root
+        });
+        return;
+    }
+    let metadata;
+    try {
+        metadata = await filesystem.lstat(absoluteRoot);
+    }
+    catch (error) {
+        assertNotCancelled(signal);
+        if (isMissingMarkdownFilesystemError(error)) {
+            addIssue(collector, {
+                kind: "root-missing",
+                message: "Configured Markdown root does not exist.",
+                repositoryPath: root
+            });
+            return;
+        }
+        throwMarkdownFilesystemUnavailable(error, "inspecting a configured Markdown root");
+    }
+    assertNotCancelled(signal);
+    if (metadata.isSymbolicLink()) {
+        addIssue(collector, {
+            kind: "symbolic-link",
+            message: "Configured Markdown root must not be a symbolic link.",
+            repositoryPath: root
+        });
+        return;
+    }
+    if (!metadata.isDirectory()) {
+        addIssue(collector, {
+            kind: "root-not-directory",
+            message: "Configured Markdown root must be a directory.",
+            repositoryPath: root
+        });
+        return;
+    }
+    await walkDirectory(walk, absoluteRoot, root);
+}
+async function inspectDirectoryEntry(walk, candidate) {
+    const { collector, filesystem, reader, repository: context, signal } = walk;
+    const candidateRepositoryPath = markdownRepositoryPath(context.canonicalRoot, candidate);
+    if (collector.documents.has(candidateRepositoryPath)) {
+        return;
+    }
+    let metadata;
+    try {
+        metadata = await filesystem.lstat(candidate);
+    }
+    catch (error) {
+        assertNotCancelled(signal);
+        if (isMissingMarkdownFilesystemError(error)) {
+            return;
+        }
+        throwMarkdownFilesystemUnavailable(error, "inspecting a Markdown source entry");
+    }
+    assertNotCancelled(signal);
+    if (metadata.isSymbolicLink()) {
+        addIssue(collector, {
+            kind: "symbolic-link",
+            message: "Markdown source tree must not contain symbolic links.",
+            repositoryPath: candidateRepositoryPath
+        });
+        return;
+    }
+    if (metadata.isDirectory()) {
+        await walkDirectory(walk, candidate);
+        return;
+    }
+    if (!metadata.isFile() || extname(candidate).toLowerCase() !== ".md") {
+        return;
+    }
+    if (metadata.size > MAX_MARKDOWN_BYTES) {
+        addIssue(collector, {
+            kind: "source-too-large",
+            message: `Markdown source exceeds ${MAX_MARKDOWN_BYTES} bytes.`,
+            repositoryPath: candidateRepositoryPath
+        });
+        return;
+    }
+    const estimatedDocumentBytes = collector.estimatedDocumentBytes + metadata.size;
+    if (collector.documents.size >= MAX_MARKDOWN_DOCUMENTS ||
+        estimatedDocumentBytes > MAX_MARKDOWN_TOTAL_BYTES) {
+        resourceLimit(`Markdown observation exceeds ${MAX_MARKDOWN_DOCUMENTS} documents or ${MAX_MARKDOWN_TOTAL_BYTES} bytes.`);
+    }
+    const document = await reader.read(context, candidate, signal);
+    if (document === undefined) {
+        try {
+            await filesystem.lstat(candidate);
+        }
+        catch (error) {
+            assertNotCancelled(signal);
+            if (isMissingMarkdownFilesystemError(error)) {
+                return;
+            }
+            throwMarkdownFilesystemUnavailable(error, "rechecking a Markdown source entry");
+        }
+        assertNotCancelled(signal);
+        addIssue(collector, {
+            kind: "source-unreadable",
+            message: "Markdown source could not be read.",
+            repositoryPath: candidateRepositoryPath
+        });
+        return;
+    }
+    const nextDocumentBytes = collector.documentBytes + Buffer.byteLength(document.source, "utf8");
+    if (nextDocumentBytes > MAX_MARKDOWN_TOTAL_BYTES) {
+        resourceLimit(`Markdown observation exceeds ${MAX_MARKDOWN_TOTAL_BYTES} bytes after contained reads.`);
+    }
+    const nextReferenceCount = collector.documentReferences + document.references.length;
+    if (nextReferenceCount > MAX_MARKDOWN_REFERENCES) {
+        resourceLimit(`Markdown observation exceeds ${MAX_MARKDOWN_REFERENCES} references.`);
+    }
+    collector.documentBytes = nextDocumentBytes;
+    collector.documentReferences = nextReferenceCount;
+    collector.estimatedDocumentBytes = estimatedDocumentBytes;
+    collector.documents.set(document.repositoryPath, document);
+}
+async function walkDirectory(walk, directory, configuredRoot) {
+    const { collector, filesystem, signal } = walk;
+    assertNotCancelled(signal);
+    if (await markdownPathTraversesSymbolicLink(walk.repository.canonicalRoot, directory, filesystem, signal)) {
+        addIssue(collector, {
+            kind: "symbolic-link",
+            message: "Markdown source directory became a symbolic link during observation.",
+            repositoryPath: markdownRepositoryPath(walk.repository.canonicalRoot, directory)
+        });
+        return;
+    }
+    let entries;
+    try {
+        entries = await filesystem.readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        assertNotCancelled(signal);
+        if (isMissingMarkdownFilesystemError(error)) {
+            if (configuredRoot !== undefined) {
+                addIssue(collector, {
+                    kind: "root-missing",
+                    message: "Configured Markdown root does not exist.",
+                    repositoryPath: configuredRoot
+                });
+            }
+            return;
+        }
+        throwMarkdownFilesystemUnavailable(error, "reading a Markdown source directory");
+    }
+    assertNotCancelled(signal);
+    if (await markdownPathTraversesSymbolicLink(walk.repository.canonicalRoot, directory, filesystem, signal)) {
+        addIssue(collector, {
+            kind: "symbolic-link",
+            message: "Markdown source directory changed during observation.",
+            repositoryPath: markdownRepositoryPath(walk.repository.canonicalRoot, directory)
+        });
+        return;
+    }
+    for (const entry of entries.toSorted((left, right) => compareBinaryStrings(left.name, right.name))) {
+        assertNotCancelled(signal);
+        if (!SKIPPED_DIRECTORY_NAMES.has(entry.name)) {
+            await inspectDirectoryEntry(walk, resolve(directory, entry.name));
+        }
+    }
+}
+export async function observeFilesystemMarkdownTree(request, reader, filesystem = nodeFilesystemMarkdownOperations) {
+    assertNotCancelled(request.signal);
+    reader.reset();
+    const context = await createFilesystemMarkdownRepositoryContext(request.consumerRoot, filesystem, request.signal);
+    assertNotCancelled(request.signal);
+    const collector = {
+        documentBytes: 0,
+        documentReferences: 0,
+        estimatedDocumentBytes: 0,
+        documents: new Map(),
+        issues: []
+    };
+    const walk = {
+        collector,
+        filesystem,
+        reader,
+        repository: context,
+        ...(request.signal === undefined ? {} : { signal: request.signal })
+    };
+    for (const root of request.roots.toSorted()) {
+        await walkConfiguredRoot(walk, root);
+    }
+    return {
+        documents: [...collector.documents.values()].toSorted((left, right) => compareBinaryStrings(left.repositoryPath, right.repositoryPath)),
+        issues: collector.issues.toSorted((left, right) => compareBinaryStrings(left.repositoryPath, right.repositoryPath) ||
+            compareBinaryStrings(left.kind, right.kind))
+    };
+}
+//# sourceMappingURL=filesystem-markdown-tree-observer.js.map