tgo-wiki 0.1.0

package/packages/core/src/validation/source-reference-validator.ts

@@ -0,0 +1,191 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { assertValidSourceId } from "../sources/source-id.js";
+import { sourceMetadataPath, sourceRawMarkdownPath } from "../sources/source-paths.js";
+import { parseSourceMetadata } from "../sources/source-validator.js";
+
+export type SourceReferenceIssue = {
+  path: string;
+  code: "broken_link";
+  message: string;
+};
+
+export type SourceDirectoryValidation = {
+  source_id: string;
+  ok: boolean;
+  message?: string;
+};
+
+export async function validateSourceReferences(
+  worktreeRoot: string,
+  wikiPath: string,
+  sourceIds: string[] | undefined
+): Promise<SourceReferenceIssue[]> {
+  if (!sourceIds || sourceIds.length === 0) {
+    return [];
+  }
+
+  const issues: SourceReferenceIssue[] = [];
+
+  for (const sourceId of sourceIds) {
+    const validation = await validateSourceDirectory(worktreeRoot, sourceId);
+
+    if (!validation.ok) {
+      issues.push({
+        path: wikiPath,
+        code: "broken_link",
+        message: validation.message ?? `Source reference does not resolve: ${sourceId}`
+      });
+    }
+  }
+
+  return issues;
+}
+
+export async function validateSourceDirectory(worktreeRoot: string, sourceId: string): Promise<SourceDirectoryValidation> {
+  try {
+    assertValidSourceId(sourceId);
+
+    const sourcesRoot = path.join(worktreeRoot, "sources");
+    const sourceRoot = path.join(sourcesRoot, sourceId);
+    const metadataPath = sourceMetadataPath(worktreeRoot, sourceId);
+    const rawMarkdownPath = sourceRawMarkdownPath(worktreeRoot, sourceId);
+
+    await assertDirectoryNotSymlink(sourcesRoot);
+    await assertDirectoryNotSymlink(sourceRoot);
+    await assertFileNotSymlink(metadataPath);
+    await assertFileNotSymlink(rawMarkdownPath);
+
+    const realSourceRoot = await realpath(sourceRoot);
+    const realMetadataPath = await realpath(metadataPath);
+    const realRawMarkdownPath = await realpath(rawMarkdownPath);
+
+    if (!isInsideRealRoot(realSourceRoot, realMetadataPath) || !isInsideRealRoot(realSourceRoot, realRawMarkdownPath)) {
+      return {
+        source_id: sourceId,
+        ok: false,
+        message: `Source files escape source directory: ${sourceId}`
+      };
+    }
+
+    const metadata = parseSourceMetadata(JSON.parse(await readFile(metadataPath, "utf8")));
+
+    if (metadata.documentId !== sourceId || metadata.rawMarkdownPath !== `sources/${sourceId}/raw.md`) {
+      return {
+        source_id: sourceId,
+        ok: false,
+        message: `Source metadata does not match source id: ${sourceId}`
+      };
+    }
+
+    return {
+      source_id: sourceId,
+      ok: true
+    };
+  } catch (error) {
+    return {
+      source_id: sourceId,
+      ok: false,
+      message: error instanceof Error ? error.message : `Source reference does not resolve: ${sourceId}`
+    };
+  }
+}
+
+export async function validateSourceAssetPaths(
+  worktreeRoot: string,
+  sourceId: string,
+  assetPaths: string[]
+): Promise<SourceDirectoryValidation> {
+  try {
+    assertValidSourceId(sourceId);
+
+    const sourceRoot = path.join(worktreeRoot, "sources", sourceId);
+    const assetsRoot = path.join(sourceRoot, "assets");
+    await assertDirectoryNotSymlink(sourceRoot);
+
+    if (!(await pathExists(assetsRoot))) {
+      return {
+        source_id: sourceId,
+        ok: true
+      };
+    }
+
+    await assertDirectoryNotSymlink(assetsRoot);
+    const realAssetsRoot = await realpath(assetsRoot);
+
+    for (const assetPath of assetPaths) {
+      if (!assetPath.startsWith(`sources/${sourceId}/assets/`)) {
+        throw new Error(`Invalid source asset path: ${assetPath}`);
+      }
+
+      const assetFilePath = path.join(worktreeRoot, ...assetPath.split("/"));
+      let stat;
+
+      try {
+        stat = await lstat(assetFilePath);
+      } catch (error) {
+        if (isEnoent(error)) {
+          continue;
+        }
+
+        throw error;
+      }
+
+      if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`Unsafe source asset path: ${assetPath}`);
+      }
+
+      if (!isInsideRealRoot(realAssetsRoot, await realpath(assetFilePath))) {
+        throw new Error(`Source asset escapes assets directory: ${assetPath}`);
+      }
+    }
+
+    return {
+      source_id: sourceId,
+      ok: true
+    };
+  } catch (error) {
+    return {
+      source_id: sourceId,
+      ok: false,
+      message: error instanceof Error ? error.message : `Source asset validation failed: ${sourceId}`
+    };
+  }
+}
+
+async function assertDirectoryNotSymlink(directoryPath: string): Promise<void> {
+  const stat = await lstat(directoryPath);
+
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`Unsafe source directory: ${directoryPath}`);
+  }
+}
+
+async function assertFileNotSymlink(filePath: string): Promise<void> {
+  const stat = await lstat(filePath);
+
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`Unsafe source file path: ${filePath}`);
+  }
+}
+
+function isInsideRealRoot(realRoot: string, target: string): boolean {
+  return target.startsWith(`${realRoot}${path.sep}`) && target !== realRoot;
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await lstat(filePath);
+    return true;
+  } catch (error) {
+    if (isEnoent(error)) {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+function isEnoent(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}

package/packages/core/src/validation/validation-service.ts

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+import { firstH1, findMarkdownLinks } from "../markdown/markdown-scanner.js";
+import { WikiError } from "../errors.js";
+import { parseFrontmatter, type FrontmatterIssue } from "./frontmatter-validator.js";
+import { validateLinks, type LinkValidationIssue } from "./link-validator.js";
+import { normalizeWikiPath, resolveInsideRoot } from "./path-validator.js";
+import { validateSourceReferences, type SourceReferenceIssue } from "./source-reference-validator.js";
+
+export type ValidationErrorCode = "invalid_path" | "invalid_frontmatter" | "missing_h1" | "broken_link";
+export type ValidationWarningCode = "title_h1_mismatch";
+
+export type ValidationError = {
+  path: string;
+  code: ValidationErrorCode;
+  message: string;
+};
+
+export type ValidationWarning = {
+  path: string;
+  code: ValidationWarningCode;
+  message: string;
+};
+
+export type ValidationResult = {
+  ok: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+};
+
+export class ValidationService {
+  constructor(private readonly worktreeRoot: string) {}
+
+  async validatePaths(paths: string[]): Promise<ValidationResult> {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+
+    for (const inputPath of paths) {
+      let wikiPath: string;
+      let absolutePath: string;
+
+      try {
+        wikiPath = normalizeWikiPath(inputPath);
+        absolutePath = resolveInsideRoot(this.worktreeRoot, wikiPath);
+      } catch (error) {
+        errors.push(pathError(inputPath, error));
+        continue;
+      }
+
+      let source: string;
+
+      try {
+        source = await readFile(absolutePath, "utf8");
+      } catch (error) {
+        errors.push({
+          path: wikiPath,
+          code: "invalid_path",
+          message: error instanceof Error ? error.message : `Unable to read Markdown file: ${wikiPath}`
+        });
+        continue;
+      }
+
+      const { page, issues: frontmatterIssues } = parseFrontmatter(wikiPath, source);
+      errors.push(...frontmatterIssues.map(toValidationError));
+
+      const h1 = firstH1(page.content);
+
+      if (!h1) {
+        errors.push({
+          path: wikiPath,
+          code: "missing_h1",
+          message: `Markdown file is missing an H1 heading: ${wikiPath}`
+        });
+      } else if (page.frontmatter.title && page.frontmatter.title !== h1) {
+        warnings.push({
+          path: wikiPath,
+          code: "title_h1_mismatch",
+          message: `Frontmatter title "${page.frontmatter.title}" does not match H1 "${h1}"`
+        });
+      }
+
+      const links = findMarkdownLinks(page.content);
+      errors.push(...(await validateLinks(this.worktreeRoot, wikiPath, links)).map(toValidationError));
+      errors.push(
+        ...(await validateSourceReferences(this.worktreeRoot, wikiPath, page.frontmatter.sources)).map(toValidationError)
+      );
+    }
+
+    return {
+      ok: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+}
+
+function pathError(inputPath: string, error: unknown): ValidationError {
+  return {
+    path: inputPath,
+    code: "invalid_path",
+    message: error instanceof WikiError ? error.message : `Invalid wiki path: ${inputPath}`
+  };
+}
+
+function toValidationError(issue: FrontmatterIssue | LinkValidationIssue | SourceReferenceIssue): ValidationError {
+  return issue;
+}

package/packages/core/src/vfs/vfs-command-parser.ts

@@ -0,0 +1,69 @@
+import { WikiError } from "../errors.js";
+
+export type VfsCommandName = "pwd" | "ls" | "find" | "cat" | "grep" | "head" | "tail" | "wc" | "tree";
+
+export type VfsCommand = {
+  name: VfsCommandName;
+  args: string[];
+};
+
+const allowedCommands = new Set<VfsCommandName>(["pwd", "ls", "find", "cat", "grep", "head", "tail", "wc", "tree"]);
+
+export function parseVfsCommand(command: string): VfsCommand {
+  const tokens = tokenize(command);
+  const [name, ...args] = tokens;
+
+  if (!name || !isVfsCommandName(name)) {
+    throw new WikiError("vfs_command_denied", `Unsupported VFS command: ${name ?? ""}`.trim());
+  }
+
+  return { name, args };
+}
+
+function isVfsCommandName(value: string): value is VfsCommandName {
+  return allowedCommands.has(value as VfsCommandName);
+}
+
+function tokenize(input: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "'" | "\"" | undefined;
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+
+    if (quote) {
+      if (char === quote) {
+        quote = undefined;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === "\"") {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (quote) {
+    throw new WikiError("vfs_command_denied", "Unterminated quoted string");
+  }
+
+  if (current.length > 0) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}