waymark-docs 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to Waymark are documented in this file.
+
+## 0.1.0 (2026-07-31)
+
+- Initial public release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Aran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,302 @@
+# Waymark 🪧
+
+Find the right repository docs for your coding agent.
+
+Waymark is a small, offline-first CLI built for AI agents. Add structured
+frontmatter to Markdown or MDX files, then let the agent select the kinds and
+tags relevant to its task. Waymark returns deterministic matches without
+ranking results or maintaining an index.
+
+This makes documentation discovery token-efficient: agents spend less time
+searching unrelated files and more time working with the context they need.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Commands](#commands)
+  - [`waymark init`](#waymark-init)
+  - [`waymark status`](#waymark-status)
+  - [`waymark find`](#waymark-find)
+  - [`waymark ls`](#waymark-ls)
+  - [`waymark help`](#waymark-help)
+- [Contributing](#contributing)
+
+## Installation
+
+Install the `waymark-docs` package as a development dependency:
+
+```sh
+pnpm add -D waymark-docs
+yarn add -D waymark-docs
+bun add -d waymark-docs
+npm install --save-dev waymark-docs
+```
+
+## Quick start
+
+1. Create `waymark.yaml` in the repository root:
+
+   ```sh
+   npx waymark init
+   ```
+
+2. Define the document kinds and tags that agents can search:
+
+   ```yaml
+   # When true, document metadata must be nested under a `waymark` frontmatter key.
+   require-namespace: false
+
+   kinds:
+     adr: Read to understand past architectural decisions and their constraints
+     convention: Read before changing code to follow required repository practices
+
+   tags:
+     architecture: System boundaries, component relationships, and dependencies
+     typescript: TypeScript-related documentation
+   ```
+
+3. Register a Markdown or MDX file by adding Waymark metadata. For example,
+   save this as `docs/conventions/typescript.md`:
+
+   ```yaml
+   ---
+   kind: convention
+   description: TypeScript conventions for this repository
+   tags: [typescript]
+   ---
+   # TypeScript conventions
+   ```
+
+4. Validate the repository:
+
+   ```sh
+   npx waymark status
+   ```
+
+   ```text
+   Root: /path/to/repository
+   Status: valid
+   Waymark Documents: 1
+   Unregistered Documents: 1
+   Kinds: 2
+   Tags: 2
+   ```
+
+5. Discover the document:
+
+   ```sh
+   npx waymark find --kinds convention --tags typescript --show description
+   ```
+
+   ```text
+   docs/conventions/typescript.md — TypeScript conventions for this repository
+   ```
+
+Waymark looks for `waymark.yaml` in the current directory and its ancestors, so
+commands can also be run from a nested repository directory.
+
+## Commands
+
+| Command          | Purpose                                                   |
+| ---------------- | --------------------------------------------------------- |
+| `waymark init`   | Create a starter configuration                            |
+| `waymark status` | Validate and summarize the repository                     |
+| `waymark find`   | Find registered documents across the repository           |
+| `waymark ls`     | Audit registered or unregistered documents in a directory |
+| `waymark help`   | Show CLI or command-specific help                         |
+
+### `waymark init`
+
+Create a starter `waymark.yaml` in the current directory.
+
+```text
+Usage: waymark init [options]
+
+Options:
+  -h, --help  Display help for the command
+```
+
+```sh
+npx waymark init
+```
+
+The generated file explains metadata namespacing and includes declarations to
+replace with your own kind and tag:
+
+```yaml
+# When true, document metadata must be nested under a `waymark` frontmatter key.
+require-namespace: false
+kinds:
+  example-kind: Explain when agents should read this kind of document
+tags:
+  example-tag: Explain the topic represented by this tag
+```
+
+`init` never overwrites an existing configuration and does not allow a nested
+configuration beneath another Waymark root.
+
+### `waymark status`
+
+Validate `waymark.yaml` and all discovered Waymark Documents, then print the
+repository root and counts for registered documents, unregistered documents,
+kinds, and tags. Invalid repositories produce diagnostics and a non-zero exit
+code, which makes this command suitable for CI.
+
+```text
+Usage: waymark status [options]
+
+Options:
+  -s, --show <fields>  Show declared kind and tag details (kind,tags)
+  -h, --help           Display help for the command
+```
+
+Validate the repository:
+
+```sh
+npx waymark status
+```
+
+List every declared kind and tag with its description and usage count:
+
+```sh
+npx waymark status --show kind,tags
+```
+
+Show only kind details:
+
+```sh
+npx waymark status --show kind
+```
+
+### `waymark find`
+
+Find registered Waymark Documents across the repository. With no filters,
+`find` returns every registered document in deterministic path order.
+
+```text
+Usage: waymark find [options]
+
+Options:
+  -k, --kinds <identifiers>         Match any kind (comma-separated, repeatable)
+  -t, --tags <identifiers>          Match any tag (comma-separated, repeatable)
+  -r, --require-tags <identifiers>  Require every tag (comma-separated, repeatable)
+  -f, --filter <expression>         Match a Boolean metadata filter
+  -q, --query <text>                Match a literal content query
+  -s, --show <fields>               Show kind, tags, and description
+  --json                            Return a flat JSON array
+  --tree                            Return a directory tree
+  -h, --help                        Display help for the command
+```
+
+Simple filter values use OR within an option. Different options combine with
+AND:
+
+```sh
+# Kind is adr OR convention, and at least one tag is typescript OR architecture
+npx waymark find --kinds adr,convention --tags typescript,architecture
+
+# Kind is adr, and both architecture AND typescript tags are required
+npx waymark find --kinds adr --require-tags architecture,typescript
+```
+
+The three simple metadata filters are repeatable. Repeating an option is
+equivalent to passing a comma-separated list:
+
+```sh
+npx waymark find --kinds adr --kinds convention
+```
+
+Use `--query` for a case-insensitive literal search of document bodies. It can
+be combined with either simple or Boolean metadata filters:
+
+```sh
+npx waymark find --kinds convention --query "dependency injection"
+```
+
+Use `--filter` for advanced metadata expressions with `kind:`, `tag:`, `NOT`,
+`AND`, `OR`, and parentheses:
+
+```sh
+npx waymark find --filter '(kind:adr OR kind:convention) AND tag:typescript AND NOT tag:architecture'
+```
+
+`--filter` cannot be combined with `--kinds`, `--tags`, or `--require-tags`.
+
+Add metadata fields to the default line-oriented output with `--show`:
+
+```sh
+npx waymark find --kinds convention --show kind,tags,description
+```
+
+Return structured output for scripts and agents:
+
+```sh
+npx waymark find --tags typescript --show kind,description --json
+```
+
+Or visualize matching documents by directory:
+
+```sh
+npx waymark find --kinds adr,convention --show kind --tree
+```
+
+`--json` and `--tree` are mutually exclusive. A search with no matches succeeds
+and returns an empty result.
+
+### `waymark ls`
+
+Inventory Markdown and MDX registration within a directory. By default, `ls`
+inspects only the current directory and lists registered Waymark Documents.
+Paths are returned relative to the repository root in deterministic order.
+
+```text
+Usage: waymark ls [options] [directory]
+
+Arguments:
+  directory           Directory to inspect (defaults to the current directory)
+
+Options:
+  -R, --recursive     Inspect directories recursively
+  -u, --unregistered  List only unregistered documents
+  -h, --help          Display help for the command
+```
+
+List registered documents directly inside `docs`:
+
+```sh
+npx waymark ls docs
+```
+
+Include all nested directories:
+
+```sh
+npx waymark ls --recursive docs
+```
+
+Find Markdown and MDX files that are missing Waymark metadata:
+
+```sh
+npx waymark ls -R --unregistered docs
+```
+
+`ls` respects `.gitignore`, Waymark exclusions, and Git directory boundaries.
+The selected directory must be inside the repository root.
+
+### `waymark help`
+
+Show the command list or detailed help for one command:
+
+```text
+Usage: waymark help [command]
+```
+
+```sh
+npx waymark --help
+npx waymark help find
+npx waymark find --help
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { CommanderError, Command } from "commander";
+import packageJson from "../package.json" with { type: "json" };
+import { createFindCommand } from "./commands/find.js";
+import { createInitCommand } from "./commands/init.js";
+import { createLsCommand } from "./commands/ls.js";
+import { createStatusCommand } from "./commands/status.js";
+const program = new Command()
+    .name("waymark")
+    .description("Discover repository documentation deterministically")
+    .version(packageJson.version)
+    .exitOverride();
+program.addCommand(createInitCommand());
+program.addCommand(createStatusCommand());
+program.addCommand(createFindCommand());
+program.addCommand(createLsCommand());
+try {
+    await program.parseAsync();
+}
+catch (error) {
+    if (error instanceof CommanderError) {
+        process.exitCode = error.exitCode;
+    }
+    else {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`error: ${message}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/find.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createFindCommand(): Command;

package/dist/commands/find.js

@@ -0,0 +1,176 @@
+import { Command } from "commander";
+import { loadConfiguration } from "../configuration/index.js";
+import { compareDiagnostics, throwDiagnostics } from "../diagnostics.js";
+import { filterDocuments, scanDocuments, } from "../documents/index.js";
+export function createFindCommand() {
+    return new Command("find")
+        .description("Discover Waymark Documents")
+        .option("-k, --kinds <identifiers>", "Match any Document Kind (comma-separated, repeatable)", collectOptionValue, [])
+        .option("-t, --tags <identifiers>", "Match any Document Tag (comma-separated, repeatable)", collectOptionValue, [])
+        .option("-r, --require-tags <identifiers>", "Require every Document Tag (comma-separated, repeatable)", collectOptionValue, [])
+        .option("-f, --filter <expression>", "Match a Boolean Metadata Filter")
+        .option("-q, --query <text>", "Match a literal Content Query")
+        .option("-s, --show <fields>", "Show kind, tags, and description (comma-separated)")
+        .option("--json", "Return a flat JSON array")
+        .option("--tree", "Return a directory-tree presentation")
+        .action(async (options) => {
+        if (options.filter !== undefined &&
+            (options.kinds.length > 0 ||
+                options.tags.length > 0 ||
+                options.requireTags.length > 0)) {
+            throw new Error("--filter cannot be combined with --kinds, --tags, or --require-tags.");
+        }
+        if (options.json && options.tree) {
+            throw new Error("--json cannot be combined with --tree.");
+        }
+        const shownFields = parseShownFields(options.show);
+        const loadedConfiguration = await loadConfiguration(process.cwd());
+        if (loadedConfiguration.kind === "malformed") {
+            throwDiagnostics(loadedConfiguration.diagnostics);
+        }
+        const { configuration, rootPath } = loadedConfiguration;
+        const documentScan = await scanDocuments({ rootPath, configuration });
+        const diagnostics = [
+            ...loadedConfiguration.diagnostics,
+            ...(documentScan.kind === "invalid" ? documentScan.diagnostics : []),
+        ].sort(compareDiagnostics);
+        if (loadedConfiguration.diagnostics.length > 0 ||
+            documentScan.kind === "invalid") {
+            throwDiagnostics(diagnostics);
+        }
+        const matchingDocuments = filterDocuments({
+            documents: documentScan.documents,
+            configuration,
+            criteria: {
+                kinds: options.kinds,
+                tags: options.tags,
+                requiredTags: options.requireTags,
+                filter: options.filter,
+                query: options.query,
+            },
+        });
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(matchingDocuments.map((document) => projectDocument(document, shownFields)), undefined, 2)}\n`);
+        }
+        else if (options.tree) {
+            process.stdout.write(renderDocumentTree(matchingDocuments, shownFields));
+        }
+        else {
+            process.stdout.write(matchingDocuments
+                .map((document) => renderDocumentLine(document, shownFields))
+                .join("\n") + (matchingDocuments.length > 0 ? "\n" : ""));
+        }
+    });
+}
+function projectDocument(document, shownFields) {
+    const projection = { path: document.path };
+    if (shownFields.has("kind"))
+        projection.kind = document.kind;
+    if (shownFields.has("tags"))
+        projection.tags = document.tags;
+    if (shownFields.has("description")) {
+        projection.description = document.description;
+    }
+    return projection;
+}
+function parseShownFields(value) {
+    if (value === undefined)
+        return new Set();
+    const shownFields = new Set();
+    for (const field of value.split(",")) {
+        if (field !== "kind" && field !== "tags" && field !== "description") {
+            throw new Error(`Unknown find field "${field}". Expected kind, tags, or description.`);
+        }
+        if (shownFields.has(field)) {
+            throw new Error(`Duplicate find field "${field}".`);
+        }
+        shownFields.add(field);
+    }
+    return shownFields;
+}
+function renderDocumentLine(document, shownFields, displayedPath = document.path) {
+    let line = displayedPath;
+    if (shownFields.has("kind"))
+        line += ` [${document.kind}]`;
+    if (shownFields.has("tags"))
+        line += ` [${document.tags.join(",")}]`;
+    if (shownFields.has("description")) {
+        const description = document.description.replaceAll(/\s+/g, " ").trim();
+        line += ` — ${description}`;
+    }
+    return line;
+}
+function renderDocumentTree(documents, shownFields) {
+    const root = createTreeDirectory();
+    for (const document of documents) {
+        const pathParts = document.path.split("/");
+        const fileName = pathParts.pop();
+        if (!fileName)
+            continue;
+        let directory = root;
+        for (const pathPart of pathParts) {
+            let childDirectory = directory.directories.get(pathPart);
+            if (!childDirectory) {
+                childDirectory = createTreeDirectory();
+                directory.directories.set(pathPart, childDirectory);
+            }
+            directory = childDirectory;
+        }
+        directory.documents.set(fileName, document);
+    }
+    let output = "";
+    for (const entry of sortedTreeEntries(root)) {
+        if (entry.kind === "document") {
+            output += `${renderDocumentLine(entry.document, shownFields, entry.name)}\n`;
+        }
+        else {
+            output += `${entry.name}/\n`;
+            output += renderTreeDirectory(entry.directory, shownFields, "");
+        }
+    }
+    return output;
+}
+function renderTreeDirectory(directory, shownFields, prefix) {
+    const entries = sortedTreeEntries(directory);
+    let output = "";
+    for (const [index, entry] of entries.entries()) {
+        const isLast = index === entries.length - 1;
+        const connector = isLast ? "└── " : "├── ";
+        if (entry.kind === "document") {
+            output +=
+                `${prefix}${connector}` +
+                    `${renderDocumentLine(entry.document, shownFields, entry.name)}\n`;
+        }
+        else {
+            output += `${prefix}${connector}${entry.name}/\n`;
+            output += renderTreeDirectory(entry.directory, shownFields, `${prefix}${isLast ? "    " : "│   "}`);
+        }
+    }
+    return output;
+}
+function sortedTreeEntries(directory) {
+    return [
+        ...[...directory.directories].map(([name, childDirectory]) => ({
+            kind: "directory",
+            name,
+            directory: childDirectory,
+        })),
+        ...[...directory.documents].map(([name, document]) => ({
+            kind: "document",
+            name,
+            document,
+        })),
+    ].sort((left, right) => compareText(left.kind === "directory" ? `${left.name}/` : left.name, right.kind === "directory" ? `${right.name}/` : right.name));
+}
+function createTreeDirectory() {
+    return {
+        directories: new Map(),
+        documents: new Map(),
+    };
+}
+function collectOptionValue(value, previous) {
+    return [...previous, value];
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createInitCommand(): Command;

package/dist/commands/init.js

@@ -0,0 +1,11 @@
+import { basename } from "node:path";
+import { Command } from "commander";
+import { initializeConfiguration } from "../configuration/index.js";
+export function createInitCommand() {
+    return new Command("init")
+        .description("Create a starter Waymark configuration")
+        .action(async () => {
+        const { configurationPath } = await initializeConfiguration(process.cwd());
+        process.stdout.write(`Created ${basename(configurationPath)}\n`);
+    });
+}

package/dist/commands/ls.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createLsCommand(): Command;

package/dist/commands/ls.js

@@ -0,0 +1,39 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { loadConfiguration } from "../configuration/index.js";
+import { throwDiagnostics } from "../diagnostics.js";
+import { scanDocuments } from "../documents/index.js";
+export function createLsCommand() {
+    return new Command("ls")
+        .description("Inventory document registration in a directory")
+        .argument("[directory]", "Directory to inspect")
+        .option("-R, --recursive", "Inspect directories recursively")
+        .option("-u, --unregistered", "List only Unregistered Documents")
+        .action(async (directory, options) => {
+        const loadedConfiguration = await loadConfiguration(process.cwd());
+        if (loadedConfiguration.kind === "malformed") {
+            throwDiagnostics(loadedConfiguration.diagnostics);
+        }
+        if (loadedConfiguration.diagnostics.length > 0) {
+            throwDiagnostics(loadedConfiguration.diagnostics);
+        }
+        const rootPath = loadedConfiguration.rootPath;
+        const documentScan = await scanDocuments({
+            rootPath,
+            configuration: loadedConfiguration.configuration,
+            scope: {
+                directoryPath: resolve(process.cwd(), directory ?? "."),
+                recursive: options.recursive === true,
+            },
+        });
+        if (documentScan.kind === "invalid") {
+            throwDiagnostics(documentScan.diagnostics);
+        }
+        const paths = options.unregistered
+            ? documentScan.unregisteredDocuments
+            : documentScan.documents.map((document) => document.path);
+        const output = paths.join("\n");
+        if (output !== "")
+            process.stdout.write(`${output}\n`);
+    });
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createStatusCommand(): Command;

package/dist/commands/status.js

@@ -0,0 +1,71 @@
+import { Command } from "commander";
+import { loadConfiguration, } from "../configuration/index.js";
+import { compareDiagnostics, throwDiagnostics } from "../diagnostics.js";
+import { scanDocuments } from "../documents/index.js";
+export function createStatusCommand() {
+    return new Command("status")
+        .description("Validate and summarize the Waymark repository")
+        .option("-s, --show <fields>", "Show declared kind and tag details (kind,tags)")
+        .action(async (options) => {
+        const shownFields = parseShownFields(options.show);
+        const loadedConfiguration = await loadConfiguration(process.cwd());
+        if (loadedConfiguration.kind === "malformed") {
+            process.stdout.write(`Root: ${loadedConfiguration.rootPath}\n` + "Status: invalid\n");
+            throwDiagnostics(loadedConfiguration.diagnostics);
+        }
+        const { configuration, rootPath } = loadedConfiguration;
+        const documentScan = await scanDocuments({ rootPath, configuration });
+        const diagnostics = [
+            ...loadedConfiguration.diagnostics,
+            ...(documentScan.kind === "invalid" ? documentScan.diagnostics : []),
+        ].sort(compareDiagnostics);
+        if (loadedConfiguration.diagnostics.length > 0 ||
+            documentScan.kind === "invalid") {
+            process.stdout.write(`Root: ${rootPath}\n` + "Status: invalid\n");
+            throwDiagnostics(diagnostics);
+        }
+        let output = `Root: ${rootPath}\n` +
+            "Status: valid\n" +
+            `Waymark Documents: ${documentScan.documents.length}\n` +
+            `Unregistered Documents: ${documentScan.unregisteredDocuments.length}\n` +
+            `Kinds: ${configuration.kinds.size}\n` +
+            `Tags: ${configuration.tags.size}\n`;
+        if (shownFields.size > 0)
+            output += "\n";
+        if (shownFields.has("kind")) {
+            output += renderDeclaredValues("Kinds", configuration.kinds, documentScan.kindUsageCounts);
+        }
+        if (shownFields.has("tags")) {
+            output += renderDeclaredValues("Tags", configuration.tags, documentScan.tagUsageCounts);
+        }
+        process.stdout.write(output);
+    });
+}
+function parseShownFields(value) {
+    if (value === undefined)
+        return new Set();
+    const fields = value.split(",");
+    const shownFields = new Set();
+    for (const field of fields) {
+        if (field !== "kind" && field !== "tags") {
+            throw new Error(`Unknown status field "${field}". Expected kind or tags.`);
+        }
+        if (shownFields.has(field)) {
+            throw new Error(`Duplicate status field "${field}".`);
+        }
+        shownFields.add(field);
+    }
+    return shownFields;
+}
+function renderDeclaredValues(heading, values, usageCounts) {
+    let output = `${heading}:\n`;
+    const sortedValues = [...values.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+    for (const [identifier, value] of sortedValues) {
+        const documentCount = usageCounts.get(identifier) ?? 0;
+        const noun = documentCount === 1 ? "document" : "documents";
+        const description = value.description.replaceAll(/\s+/g, " ").trim();
+        output +=
+            `  ${identifier} — ${description} ` + `(${documentCount} ${noun})\n`;
+    }
+    return output;
+}

package/dist/configuration/index.d.ts

@@ -0,0 +1,3 @@
+export { initializeConfiguration } from "./initialize.js";
+export { configurationFileName, loadConfiguration } from "./load.js";
+export type { Configuration, ConfigurationDeclaration, ConfigurationDiagnostic, ConfigurationLoadResult, } from "./load.js";