@warpgogol/forge 2.8.0 → 2.8.2

package/src/utils/generated-marker.ts

@@ -0,0 +1,166 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Canonical GENERATED_MARKER constant and advisory header builder for
+generated-file governance. Moved from @warpgogol/site-kernel to forge as canonical
+source (dependency inversion).</purpose>
+<non-goals>
+  <item>Do not perform file I/O — operates on in-memory content strings only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Moved from @warpgogol/site-kernel/generated-marker to forge as canonical source.</item>
+  <item>Added optional commandPrefix to GeneratedHeaderInput — defaults to "forge" for autonomous mode; site-kernel passes "pnpm exec werkstatt run".</item>
+</CHANGE_SUMMARY>
+*/
+
+export const GENERATED_MARKER =
+  "GENERATED. Do not change this line unless the file contains project specific changes.";
+
+export function hasGeneratedMarker(content: string): boolean {
+  return content.includes(GENERATED_MARKER);
+}
+
+export interface StripGeneratedMarkerResult {
+  changed: boolean;
+  content: string;
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const DO_NOT_EDIT_LINE = "DO NOT EDIT THIS FILE. Changes are overwritten on the next build.";
+
+export function stripGeneratedMarker(content: string): StripGeneratedMarkerResult {
+  const raw = GENERATED_MARKER;
+  let result = content;
+  let changed = false;
+
+  const applyAll = (patterns: RegExp[]): void => {
+    for (const pattern of patterns) {
+      const next = result.replace(pattern, "");
+      if (next !== result) {
+        changed = true;
+        result = next;
+      }
+    }
+  };
+
+  applyAll([
+    new RegExp(`<!--[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?-->\\n?`, "g"),
+    new RegExp(`/\\*[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?\\*/\\n?`, "g"),
+  ]);
+
+  for (const token of ["//", "#"]) {
+    const t = escapeRegex(token);
+    const advisoryLine = (suffix: string): string => `(?:[ \\t]*${t}[ \\t]*${suffix}\\n)?`;
+    const pattern = new RegExp(
+      `^[ \\t]*${t}[ \\t]*${escapeRegex(raw)}\\n` +
+        advisoryLine(escapeRegex(DO_NOT_EDIT_LINE)) +
+        advisoryLine("Owner command:.*") +
+        advisoryLine("Edit instead:.*") +
+        advisoryLine("Regenerate:.*"),
+      "gm",
+    );
+    applyAll([pattern]);
+  }
+
+  applyAll([
+    new RegExp(`^\\s*<!--\\s*${escapeRegex(raw)}\\s*-->\\n?`, "gm"),
+    new RegExp(`^\\s*//\\s*${escapeRegex(raw)}\\n?`, "gm"),
+    new RegExp(`^\\s*/\\*\\s*${escapeRegex(raw)}\\s*\\*/\\n?`, "gm"),
+    new RegExp(`^\\s*#\\s*${escapeRegex(raw)}\\n?`, "gm"),
+    new RegExp(`^\\s*${escapeRegex(raw)}\\n?`, "gm"),
+  ]);
+
+  if (result.includes(raw)) {
+    const next = result.split(raw).join("");
+    if (next !== result) {
+      changed = true;
+      result = next;
+    }
+  }
+
+  return { changed, content: result };
+}
+
+export interface GeneratedHeaderInput {
+  filePath: string;
+  ownerCommand: string;
+  templatePath?: string;
+  site?: string;
+  /**
+   * Command prefix for the regenerate hint. Defaults to "forge" (autonomous mode).
+   * Site-kernel callers pass "pnpm exec werkstatt run" for Warpgogol context.
+   */
+  commandPrefix?: string;
+}
+
+type GeneratedHeaderCommentStyle = "line-slash" | "line-hash" | "block-html" | "block-css";
+
+function commentStyleForPath(filePath: string): GeneratedHeaderCommentStyle {
+  const lower = filePath.toLowerCase().replace(/\\/g, "/");
+  const base = lower.slice(lower.lastIndexOf("/") + 1);
+  if (
+    base === ".gitattributes" ||
+    base === "_headers" ||
+    base === "_redirects" ||
+    base.endsWith(".txt") ||
+    base.endsWith(".yml") ||
+    base.endsWith(".yaml")
+  ) {
+    return "line-hash";
+  }
+  if (base.endsWith(".md")) return "block-html";
+  if (base.endsWith(".css")) return "block-css";
+  return "line-slash";
+}
+
+export function buildGeneratedHeader(input: GeneratedHeaderInput): string {
+  const style = commentStyleForPath(input.filePath);
+  const prefix = input.commandPrefix ?? "forge";
+  const regenerateCommand = input.site
+    ? `${prefix} ${input.ownerCommand} --site ${input.site}`
+    : `${prefix} ${input.ownerCommand}`;
+  const editInstead = input.templatePath
+    ? `Edit instead: ${input.templatePath}`
+    : `Edit instead: the ${input.ownerCommand} generator source (not this file).`;
+
+  const lines = [
+    GENERATED_MARKER,
+    DO_NOT_EDIT_LINE,
+    `Owner command: ${input.ownerCommand}`,
+    editInstead,
+    `Regenerate:   ${regenerateCommand}`,
+  ];
+
+  switch (style) {
+    case "line-slash":
+      return `${lines.map((line) => `// ${line}`).join("\n")}\n`;
+    case "line-hash":
+      return `${lines.map((line) => `# ${line}`).join("\n")}\n`;
+    case "block-css":
+      return `/*\n${lines.map((line) => `  ${line}`).join("\n")}\n*/\n`;
+    case "block-html":
+      return `<!--\n${lines.map((line) => `  ${line}`).join("\n")}\n-->\n`;
+  }
+}
+
+export function isGeneratedMarkerTextCandidate(filePath: string): boolean {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  const TEXT_EXTS = new Set([
+    ".txt",
+    ".xml",
+    ".md",
+    ".yml",
+    ".yaml",
+    ".css",
+    ".js",
+    ".mjs",
+    ".ts",
+    ".json",
+    ".html",
+    ".astro",
+  ]);
+  return TEXT_EXTS.has(ext);
+}

package/src/utils/hash.ts

@@ -0,0 +1,19 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trivial hash utility — inlined from @warpgogol/fingerprint to avoid dependency.</purpose>
+<non-goals>
+  <item>Do not add non-hash utilities here — use dedicated utility modules.</item>
+  <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial inline of byteHash from @warpgogol/fingerprint/primitives.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createHash } from "node:crypto";
+
+export function byteHash(bytes: Uint8Array | string): string {
+  const input = typeof bytes === "string" ? Buffer.from(bytes, "utf8") : bytes;
+  return `sha256:${createHash("sha256").update(input).digest("hex")}`;
+}

package/src/utils/index.ts

@@ -0,0 +1,29 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for forge utilities — canonical, autonomous, no @warpgogol/* dependencies.</purpose>
+<non-goals>
+  <item>Do not add non-utility exports here — use the appropriate forge module.</item>
+  <item>Do not re-export from @warpgogol/* packages — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial utility barrel: fs-atomic, generated-marker, string-utils, fs, hash.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { writeFileAtomic, type WriteFileAtomicOptions } from "./fs-atomic.ts";
+export { writeFileIfChanged } from "./fs-idempotent.ts";
+export {
+  GENERATED_MARKER,
+  hasGeneratedMarker,
+  stripGeneratedMarker,
+  buildGeneratedHeader,
+  isGeneratedMarkerTextCandidate,
+  type GeneratedHeaderInput,
+  type StripGeneratedMarkerResult,
+} from "./generated-marker.ts";
+export { toKebabCase } from "./string-utils.ts";
+export { collectFiles, fileExists, type CollectFilesOptions } from "./fs.ts";
+export { byteHash } from "./hash.ts";
+export { trashPath } from "./fs-trash.ts";
+export { trashSync } from "./fs-trash-sync.ts";

package/src/utils/string-utils.ts

@@ -0,0 +1,19 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trivial string utilities — inlined from @warpgogol/share to avoid dependency.</purpose>
+<non-goals>
+  <item>Do not add non-string utilities here — use dedicated utility modules.</item>
+  <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial inline of toKebabCase from @warpgogol/werkstatt-shared/share/string-utils.</item>
+</CHANGE_SUMMARY>
+*/
+
+export function toKebabCase(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}

package/src/validators/__tests__/note-orphan-detect.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { runNoteOrphanDetect } from "../note-orphan-detect.ts";
+import { join } from "node:path";
+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "forge-orphan-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+async function createVaultFile(vaultDir: string, relPath: string, content: string) {
+  const fullPath = join(vaultDir, relPath);
+  const dir = join(fullPath, "..");
+  await mkdir(dir, { recursive: true });
+  await writeFile(fullPath, content, "utf8");
+}
+
+describe("runNoteOrphanDetect", () => {
+  it("returns empty when vault directory not found", () => {
+    const result = runNoteOrphanDetect(
+      { flags: { "vault-dir": "nonexistent" } },
+      { workspaceRoot: tempDir },
+    );
+    expect(result.data?.count).toBe(0);
+    expect(result.data?.orphans).toEqual([]);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("detects orphan note with zero inbound links", async () => {
+    const vaultDir = join(tempDir, "vault");
+    await mkdir(vaultDir, { recursive: true });
+    await createVaultFile(vaultDir, "linked.md", "# Linked\n\n[[target]]");
+    await createVaultFile(vaultDir, "target.md", "# Target");
+    await createVaultFile(vaultDir, "orphan.md", "# Orphan — nobody links to me");
+
+    const result = runNoteOrphanDetect(
+      { flags: { "vault-dir": "vault" } },
+      { workspaceRoot: tempDir },
+    );
+
+    const orphanFiles = result.data?.orphans.map((o) => o.file) ?? [];
+    expect(orphanFiles).toContain("vault/orphan.md");
+    expect(orphanFiles).not.toContain("vault/target.md");
+  });
+
+  it("does not flag notes that are linked via alias", async () => {
+    const vaultDir = join(tempDir, "vault");
+    await mkdir(vaultDir, { recursive: true });
+    await createVaultFile(vaultDir, "note.md", "---\naliases: [MyAlias]\n---\n# Note");
+    await createVaultFile(vaultDir, "linker.md", "# Linker\n\n[[MyAlias]]");
+
+    const result = runNoteOrphanDetect(
+      { flags: { "vault-dir": "vault" } },
+      { workspaceRoot: tempDir },
+    );
+
+    const orphanFiles = result.data?.orphans.map((o) => o.file) ?? [];
+    expect(orphanFiles).not.toContain("note.md");
+  });
+
+  it("counts self-links correctly (self-link does not count as inbound)", async () => {
+    const vaultDir = join(tempDir, "vault");
+    await mkdir(vaultDir, { recursive: true });
+    await createVaultFile(vaultDir, "self.md", "# Self\n\n[[self]]");
+
+    const result = runNoteOrphanDetect(
+      { flags: { "vault-dir": "vault" } },
+      { workspaceRoot: tempDir },
+    );
+
+    const orphanFiles = result.data?.orphans.map((o) => o.file) ?? [];
+    expect(orphanFiles).toContain("vault/self.md");
+  });
+
+  it("always returns exitCode 0 (warnings, not errors)", async () => {
+    const vaultDir = join(tempDir, "vault");
+    await mkdir(vaultDir, { recursive: true });
+    await createVaultFile(vaultDir, "orphan.md", "# Orphan");
+
+    const result = runNoteOrphanDetect(
+      { flags: { "vault-dir": "vault" } },
+      { workspaceRoot: tempDir },
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.count).toBeGreaterThan(0);
+  });
+});

package/src/validators/note-frontmatter-validate.ts

@@ -0,0 +1,142 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Validate frontmatter consistency across a markdown note vault — checks for required fields in YAML frontmatter.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not implement domain-specific logic beyond frontmatter validation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.frontmatter.validate command handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { ForgeCommandResult } from "../types.ts";
+
+interface NoteFrontmatterValidateInput {
+  flags: Record<string, unknown>;
+}
+
+export interface FrontmatterViolation {
+  file: string;
+  field: string;
+  rule: "NOTE-02";
+  message: string;
+}
+
+export interface NoteFrontmatterValidateResult {
+  command: "note.frontmatter.validate";
+  violations: FrontmatterViolation[];
+  count: number;
+}
+
+function collectMarkdownFiles(dir: string, baseDir: string, results: string[]): void {
+  const SKIP_DIRS = new Set(["node_modules", ".git", ".turbo", "dist", ".cache", ".obsidian"]);
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, "/");
+    if (entry.isDirectory()) {
+      collectMarkdownFiles(fullPath, baseDir, results);
+    } else if (entry.name.endsWith(".md")) {
+      results.push(relPath);
+    }
+  }
+}
+
+export function runNoteFrontmatterValidate(
+  input: NoteFrontmatterValidateInput,
+  context: { workspaceRoot?: string },
+): ForgeCommandResult<NoteFrontmatterValidateResult> {
+  const workspaceRoot = context.workspaceRoot ?? process.cwd();
+  const vaultDir = (input.flags["vault-dir"] as string) ?? "vault";
+  const requiredFields = ((input.flags["fields"] as string) ?? "title")
+    .split(",")
+    .map((f) => f.trim())
+    .filter(Boolean);
+
+  const scanDir = path.join(workspaceRoot, vaultDir);
+
+  if (!fs.existsSync(scanDir)) {
+    return {
+      data: {
+        command: "note.frontmatter.validate",
+        violations: [],
+        count: 0,
+      },
+      exitCode: 0,
+      summary: "note.frontmatter.validate: vault directory not found — 0 violations",
+    };
+  }
+
+  const allMdFiles: string[] = [];
+  collectMarkdownFiles(scanDir, workspaceRoot, allMdFiles);
+
+  const violations: FrontmatterViolation[] = [];
+
+  for (const file of allMdFiles) {
+    const fullPath = path.join(workspaceRoot, file);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (!fmMatch) {
+        for (const field of requiredFields) {
+          violations.push({
+            file,
+            field,
+            rule: "NOTE-02",
+            message: `File '${file}' has no frontmatter — missing field '${field}'`,
+          });
+        }
+        continue;
+      }
+      let fm: Record<string, unknown> = {};
+      try {
+        fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+      } catch {
+        for (const field of requiredFields) {
+          violations.push({
+            file,
+            field,
+            rule: "NOTE-02",
+            message: `File '${file}' has malformed frontmatter — missing field '${field}'`,
+          });
+        }
+        continue;
+      }
+      for (const field of requiredFields) {
+        if (!(field in fm) || fm[field] == null || fm[field] === "") {
+          if (field === "title") {
+            const hasH1 = /^\s*#\s+\S/.test(content.slice(fmMatch[0].length));
+            if (hasH1) continue;
+          }
+          violations.push({
+            file,
+            field,
+            rule: "NOTE-02",
+            message: `File '${file}' missing required field '${field}'`,
+          });
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  return {
+    data: {
+      command: "note.frontmatter.validate",
+      violations,
+      count: violations.length,
+    },
+    exitCode: violations.length > 0 ? 1 : 0,
+    summary:
+      violations.length > 0
+        ? `note.frontmatter.validate: ${violations.length} violation(s) found`
+        : "note.frontmatter.validate: OK — 0 violations",
+  };
+}

package/src/validators/note-link-validate.ts

@@ -0,0 +1,145 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Validate wikilink integrity across a markdown note vault — scans [[wikilinks]] and resolves each against the note graph.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not implement domain-specific logic beyond wikilink resolution.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.link.validate command handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { ForgeCommandResult } from "../types.ts";
+
+interface NoteLinkValidateInput {
+  flags: Record<string, unknown>;
+}
+
+export interface NoteLinkViolation {
+  file: string;
+  line: number;
+  link: string;
+  rule: "NOTE-01";
+  message: string;
+}
+
+export interface NoteLinkValidateResult {
+  command: "note.link.validate";
+  violations: NoteLinkViolation[];
+  count: number;
+}
+
+function collectMarkdownFiles(dir: string, baseDir: string, results: string[]): void {
+  const SKIP_DIRS = new Set(["node_modules", ".git", ".turbo", "dist", ".cache", ".obsidian"]);
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, "/");
+    if (entry.isDirectory()) {
+      collectMarkdownFiles(fullPath, baseDir, results);
+    } else if (entry.name.endsWith(".md")) {
+      results.push(relPath);
+    }
+  }
+}
+
+export function runNoteLinkValidate(
+  input: NoteLinkValidateInput,
+  context: { workspaceRoot?: string },
+): ForgeCommandResult<NoteLinkValidateResult> {
+  const workspaceRoot = context.workspaceRoot ?? process.cwd();
+  const vaultDir = (input.flags["vault-dir"] as string) ?? "vault";
+  const pathFilter = input.flags["path"] as string | undefined;
+  const scanDir = pathFilter
+    ? path.join(workspaceRoot, vaultDir, pathFilter)
+    : path.join(workspaceRoot, vaultDir);
+
+  if (!fs.existsSync(scanDir)) {
+    return {
+      data: {
+        command: "note.link.validate",
+        violations: [],
+        count: 0,
+      },
+      exitCode: 0,
+      summary: "note.link.validate: vault directory not found — 0 violations",
+    };
+  }
+
+  const allMdFiles: string[] = [];
+  collectMarkdownFiles(scanDir, workspaceRoot, allMdFiles);
+
+  const noteMap = new Map<string, string>();
+  for (const mdFile of allMdFiles) {
+    const basename = path.basename(mdFile, ".md");
+    noteMap.set(basename, mdFile);
+    const fullPath = path.join(workspaceRoot, mdFile);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (fmMatch) {
+        try {
+          const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+          if (fm.aliases && Array.isArray(fm.aliases)) {
+            for (const alias of fm.aliases) {
+              if (typeof alias === "string") noteMap.set(alias, mdFile);
+            }
+          }
+        } catch {
+          // skip malformed frontmatter
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const linkRegex = /\[\[([^\]]+?)\]\]/g;
+  const violations: NoteLinkViolation[] = [];
+
+  for (const file of allMdFiles) {
+    const fullPath = path.join(workspaceRoot, file);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      const lines = content.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        let match: RegExpExecArray | null;
+        linkRegex.lastIndex = 0;
+        while ((match = linkRegex.exec(lines[i])) !== null) {
+          const linkTarget = match[1].split("|")[0].split("#")[0].trim();
+          if (!linkTarget) continue;
+          if (!noteMap.has(linkTarget)) {
+            violations.push({
+              file,
+              line: i + 1,
+              link: match[0],
+              rule: "NOTE-01",
+              message: `Wikilink target '${linkTarget}' not found in vault`,
+            });
+          }
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  return {
+    data: {
+      command: "note.link.validate",
+      violations,
+      count: violations.length,
+    },
+    exitCode: violations.length > 0 ? 1 : 0,
+    summary:
+      violations.length > 0
+        ? `note.link.validate: ${violations.length} violation(s) found`
+        : "note.link.validate: OK — 0 violations",
+  };
+}