waymark-docs 0.1.0

package/dist/configuration/index.js

@@ -0,0 +1,2 @@
+export { initializeConfiguration } from "./initialize.js";
+export { configurationFileName, loadConfiguration } from "./load.js";

package/dist/configuration/initialize.d.ts

@@ -0,0 +1,3 @@
+export declare function initializeConfiguration(directoryPath: string): Promise<{
+    configurationPath: string;
+}>;

package/dist/configuration/initialize.js

@@ -0,0 +1,34 @@
+import { writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isErrorWithCode, pathExists } from "../filesystem.js";
+import { configurationFileName, findConfigurationPath } from "./load.js";
+const starterConfiguration = "# When true, document metadata must be nested under a `waymark` frontmatter key.\n" +
+    "require-namespace: false\n" +
+    "kinds:\n" +
+    "  example-kind: Explain when agents should read this kind of document\n" +
+    "tags:\n" +
+    "  example-tag: Explain the topic represented by this tag\n";
+export async function initializeConfiguration(directoryPath) {
+    const configurationPath = join(directoryPath, configurationFileName);
+    if (await pathExists(configurationPath)) {
+        throw new Error(`A Waymark configuration already exists at ${configurationPath}.`);
+    }
+    const ancestorConfigurationPath = await findConfigurationPath(dirname(directoryPath));
+    if (ancestorConfigurationPath) {
+        throw new Error("Cannot create a nested Waymark configuration because one already " +
+            `exists at ${ancestorConfigurationPath}.`);
+    }
+    try {
+        await writeFile(configurationPath, starterConfiguration, {
+            encoding: "utf8",
+            flag: "wx",
+        });
+    }
+    catch (error) {
+        if (isErrorWithCode(error, "EEXIST")) {
+            throw new Error(`A Waymark configuration already exists at ${configurationPath}.`);
+        }
+        throw error;
+    }
+    return { configurationPath };
+}

package/dist/configuration/load.d.ts

@@ -0,0 +1,27 @@
+export declare const configurationFileName: string;
+export type ConfigurationDeclaration = {
+    description: string;
+};
+export type ConfigurationDiagnostic = {
+    path: string;
+    field: string;
+    message: string;
+};
+export type Configuration = {
+    requireNamespace: boolean;
+    kinds: Map<string, ConfigurationDeclaration>;
+    tags: Map<string, ConfigurationDeclaration>;
+    exclusions: string[];
+};
+export type ConfigurationLoadResult = {
+    kind: "loaded";
+    rootPath: string;
+    configuration: Configuration;
+    diagnostics: ConfigurationDiagnostic[];
+} | {
+    kind: "malformed";
+    rootPath: string;
+    diagnostics: ConfigurationDiagnostic[];
+};
+export declare function loadConfiguration(startingDirectoryPath: string): Promise<ConfigurationLoadResult>;
+export declare function findConfigurationPath(startingDirectoryPath: string): Promise<string | undefined>;

package/dist/configuration/load.js

@@ -0,0 +1,174 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { pathExists } from "../filesystem.js";
+export const configurationFileName = "waymark.yaml";
+export async function loadConfiguration(startingDirectoryPath) {
+    const configurationPath = await findConfigurationPath(startingDirectoryPath);
+    if (!configurationPath) {
+        throw new Error(`Could not find ${configurationFileName} from ${resolve(startingDirectoryPath)}.`);
+    }
+    const rootPath = dirname(configurationPath);
+    let parsedConfiguration;
+    try {
+        parsedConfiguration = parse(await readFile(configurationPath, "utf8"));
+    }
+    catch {
+        return {
+            kind: "malformed",
+            rootPath,
+            diagnostics: [
+                {
+                    path: configurationFileName,
+                    field: "configuration",
+                    message: "Malformed YAML configuration.",
+                },
+            ],
+        };
+    }
+    const diagnostics = [];
+    return {
+        kind: "loaded",
+        rootPath,
+        configuration: validateConfiguration(parsedConfiguration, diagnostics),
+        diagnostics,
+    };
+}
+export async function findConfigurationPath(startingDirectoryPath) {
+    let directoryPath = resolve(startingDirectoryPath);
+    let foundConfigurationPath;
+    while (true) {
+        const configurationPath = join(directoryPath, configurationFileName);
+        if (await pathExists(configurationPath)) {
+            foundConfigurationPath = configurationPath;
+        }
+        const parentPath = dirname(directoryPath);
+        if (parentPath === directoryPath)
+            return foundConfigurationPath;
+        directoryPath = parentPath;
+    }
+}
+function validateConfiguration(value, diagnostics) {
+    if (!isRecord(value)) {
+        diagnostics.push({
+            path: configurationFileName,
+            field: "configuration",
+            message: "Expected a mapping.",
+        });
+    }
+    const configuration = isRecord(value) ? value : {};
+    const allowedFields = new Set([
+        "require-namespace",
+        "kinds",
+        "tags",
+        "exclude",
+    ]);
+    for (const field of Object.keys(configuration)) {
+        if (!allowedFields.has(field)) {
+            diagnostics.push({
+                path: configurationFileName,
+                field,
+                message: "Unknown field.",
+            });
+        }
+    }
+    if (configuration["require-namespace"] !== undefined &&
+        typeof configuration["require-namespace"] !== "boolean") {
+        diagnostics.push({
+            path: configurationFileName,
+            field: "require-namespace",
+            message: "Expected a boolean.",
+        });
+    }
+    return {
+        requireNamespace: configuration["require-namespace"] === true,
+        kinds: validateDeclarations({
+            value: configuration.kinds,
+            field: "kinds",
+            diagnostics,
+        }),
+        tags: validateDeclarations({
+            value: configuration.tags,
+            field: "tags",
+            diagnostics,
+        }),
+        exclusions: validateExclusions(configuration.exclude, diagnostics),
+    };
+}
+function validateDeclarations({ value, field, diagnostics, }) {
+    if (!isRecord(value)) {
+        diagnostics.push({
+            path: configurationFileName,
+            field,
+            message: "Expected a mapping.",
+        });
+        return new Map();
+    }
+    const declarations = new Map();
+    for (const [identifier, description] of Object.entries(value)) {
+        const diagnosticField = `${field}.${identifier}`;
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(identifier)) {
+            diagnostics.push({
+                path: configurationFileName,
+                field: diagnosticField,
+                message: "Identifier must use lowercase kebab-case.",
+            });
+        }
+        if (typeof description !== "string" || description.trim() === "") {
+            diagnostics.push({
+                path: configurationFileName,
+                field: diagnosticField,
+                message: "Description must be a non-empty string.",
+            });
+        }
+        declarations.set(identifier, {
+            description: typeof description === "string" ? description : "",
+        });
+    }
+    return declarations;
+}
+function validateExclusions(value, diagnostics) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        diagnostics.push({
+            path: configurationFileName,
+            field: "exclude",
+            message: "Expected a sequence of exclusion globs.",
+        });
+        return [];
+    }
+    const exclusions = [];
+    for (const [index, pattern] of value.entries()) {
+        const field = `exclude.${index}`;
+        if (typeof pattern !== "string" || pattern.trim() === "") {
+            diagnostics.push({
+                path: configurationFileName,
+                field,
+                message: "Exclusion glob must be a non-empty string.",
+            });
+            continue;
+        }
+        if (pattern.startsWith("!")) {
+            diagnostics.push({
+                path: configurationFileName,
+                field,
+                message: "Negation is not supported in exclusion globs.",
+            });
+            continue;
+        }
+        if (/[![\]{}()]/.test(pattern)) {
+            diagnostics.push({
+                path: configurationFileName,
+                field,
+                message: "Only *, ?, and ** wildcard syntax is supported.",
+            });
+            continue;
+        }
+        exclusions.push(pattern);
+    }
+    return exclusions;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,7 @@
+export type Diagnostic = {
+    path: string;
+    field: string;
+    message: string;
+};
+export declare function throwDiagnostics(diagnostics: Diagnostic[]): never;
+export declare function compareDiagnostics(left: Diagnostic, right: Diagnostic): number;

package/dist/diagnostics.js

@@ -0,0 +1,13 @@
+export function throwDiagnostics(diagnostics) {
+    throw new Error(diagnostics
+        .map((diagnostic) => `${diagnostic.path}: ${diagnostic.field}: ${diagnostic.message}`)
+        .join("\nerror: "));
+}
+export function compareDiagnostics(left, right) {
+    return (compareText(left.path, right.path) ||
+        compareText(left.field, right.field) ||
+        compareText(left.message, right.message));
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/documents/classify.d.ts

@@ -0,0 +1,29 @@
+import type { ConfigurationDeclaration } from "../configuration/index.js";
+type ClassifiedDocument = {
+    kind: string;
+    description: string;
+    tags: string[];
+    body: string;
+};
+type DocumentDiagnostic = {
+    path: string;
+    field: string;
+    message: string;
+};
+type DocumentClassification = {
+    kind: "unregistered";
+} | {
+    kind: "invalid";
+    diagnostics: DocumentDiagnostic[];
+} | {
+    kind: "registered";
+    document: ClassifiedDocument;
+};
+export declare function classifyDocument({ source, requireNamespace, declaredKinds, declaredTags, path, }: {
+    source: string;
+    requireNamespace: boolean;
+    declaredKinds: Map<string, ConfigurationDeclaration>;
+    declaredTags: Map<string, ConfigurationDeclaration>;
+    path: string;
+}): DocumentClassification;
+export {};

package/dist/documents/classify.js

@@ -0,0 +1,203 @@
+import { parse } from "yaml";
+export function classifyDocument({ source, requireNamespace, declaredKinds, declaredTags, path, }) {
+    const frontmatter = readFrontmatter(source);
+    if (frontmatter.kind === "malformed") {
+        return {
+            kind: "invalid",
+            diagnostics: [
+                {
+                    path,
+                    field: "frontmatter",
+                    message: "Malformed YAML frontmatter.",
+                },
+            ],
+        };
+    }
+    if (frontmatter.kind === "none" || !isRecord(frontmatter.value)) {
+        return { kind: "unregistered" };
+    }
+    return validateRegistration({
+        frontmatter: frontmatter.value,
+        body: frontmatter.body,
+        requireNamespace,
+        declaredKinds,
+        declaredTags,
+        path,
+    });
+}
+function readFrontmatter(source) {
+    if (!source.startsWith("---\n") && !source.startsWith("---\r\n")) {
+        return { kind: "none" };
+    }
+    const match = /^---\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m.exec(source);
+    if (!match)
+        return { kind: "malformed" };
+    try {
+        return {
+            kind: "parsed",
+            value: parse(match[1]),
+            body: source.slice(match[0].length),
+        };
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+}
+function validateRegistration({ frontmatter, body, requireNamespace, declaredKinds, declaredTags, path, }) {
+    const hasNamespace = Object.hasOwn(frontmatter, "waymark");
+    const hasRecognizedFlatMetadata = Object.hasOwn(frontmatter, "kind") &&
+        Object.hasOwn(frontmatter, "description");
+    if (requireNamespace && !hasNamespace)
+        return { kind: "unregistered" };
+    if (!requireNamespace && !hasNamespace && !hasRecognizedFlatMetadata) {
+        return { kind: "unregistered" };
+    }
+    const diagnostics = [];
+    if (hasNamespace && hasRecognizedFlatMetadata) {
+        diagnostics.push({
+            path,
+            field: "waymark",
+            message: "Flat and namespaced metadata cannot both be declared.",
+        });
+        return { kind: "invalid", diagnostics };
+    }
+    const namespaced = hasNamespace;
+    const value = namespaced ? frontmatter.waymark : frontmatter;
+    const fieldPrefix = namespaced ? "waymark." : "";
+    if (!isRecord(value)) {
+        diagnostics.push({
+            path,
+            field: namespaced ? "waymark" : "frontmatter",
+            message: "Expected a mapping.",
+        });
+        return { kind: "invalid", diagnostics };
+    }
+    if (namespaced) {
+        const allowedFields = new Set(["kind", "description", "tags"]);
+        for (const field of Object.keys(value)) {
+            if (!allowedFields.has(field)) {
+                diagnostics.push({
+                    path,
+                    field: `${fieldPrefix}${field}`,
+                    message: "Unknown field.",
+                });
+            }
+        }
+    }
+    const context = { path, declaredKinds, declaredTags, diagnostics };
+    const kind = validateDocumentKind({
+        value: value.kind,
+        field: `${fieldPrefix}kind`,
+        context,
+    });
+    const description = validateDocumentDescription({
+        value: value.description,
+        field: `${fieldPrefix}description`,
+        context,
+    });
+    const tags = validateDocumentTags({
+        value: value.tags,
+        field: `${fieldPrefix}tags`,
+        context,
+    });
+    if (diagnostics.length > 0 ||
+        kind === undefined ||
+        description === undefined ||
+        tags === undefined) {
+        return { kind: "invalid", diagnostics };
+    }
+    return {
+        kind: "registered",
+        document: { kind, description, tags, body },
+    };
+}
+function validateDocumentKind({ value, field, context, }) {
+    if (value === undefined) {
+        context.diagnostics.push({
+            path: context.path,
+            field,
+            message: "Document kind is required.",
+        });
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        context.diagnostics.push({
+            path: context.path,
+            field,
+            message: "Document kind must be a non-empty string.",
+        });
+        return undefined;
+    }
+    if (!context.declaredKinds.has(value)) {
+        context.diagnostics.push({
+            path: context.path,
+            field,
+            message: `Undeclared kind "${value}".`,
+        });
+    }
+    return value;
+}
+function validateDocumentDescription({ value, field, context, }) {
+    if (value === undefined) {
+        context.diagnostics.push({
+            path: context.path,
+            field,
+            message: "Document Description is required.",
+        });
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        context.diagnostics.push({
+            path: context.path,
+            field,
+            message: "Document Description must be a non-empty string.",
+        });
+        return undefined;
+    }
+    return value;
+}
+function validateDocumentTags({ value, field, context, }) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        context.diagnostics.push({
+            path: context.path,
+            field,
+            message: "Expected a YAML sequence of tags.",
+        });
+        return undefined;
+    }
+    const tags = [];
+    const seenTags = new Set();
+    for (const tag of value) {
+        if (typeof tag !== "string" || tag.trim() === "") {
+            context.diagnostics.push({
+                path: context.path,
+                field,
+                message: "Every tag must be a non-empty string.",
+            });
+            continue;
+        }
+        if (seenTags.has(tag)) {
+            context.diagnostics.push({
+                path: context.path,
+                field,
+                message: `Duplicate tag "${tag}".`,
+            });
+            continue;
+        }
+        seenTags.add(tag);
+        tags.push(tag);
+        if (!context.declaredTags.has(tag)) {
+            context.diagnostics.push({
+                path: context.path,
+                field,
+                message: `Undeclared tag "${tag}".`,
+            });
+        }
+    }
+    return tags;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/documents/filter.d.ts

@@ -0,0 +1,24 @@
+import type { Configuration } from "../configuration/index.js";
+import type { WaymarkDocument } from "./scan.js";
+type FilterableDocument = {
+    kind: string;
+    tags: string[];
+};
+type DocumentCriteria = {
+    kinds: string[];
+    tags: string[];
+    requiredTags: string[];
+    filter?: string;
+    query?: string;
+};
+export declare function filterDocuments({ documents, configuration, criteria, }: {
+    documents: WaymarkDocument[];
+    configuration: Configuration;
+    criteria: DocumentCriteria;
+}): WaymarkDocument[];
+export declare function parseMetadataFilter({ expression, declaredKinds, declaredTags, }: {
+    expression: string;
+    declaredKinds: Set<string>;
+    declaredTags: Set<string>;
+}): (document: FilterableDocument) => boolean;
+export {};