@warpgogol/forge 2.8.0 → 2.8.2

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

@@ -0,0 +1,146 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Detect orphan notes in a markdown note vault — notes with zero inbound wikilinks.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not implement domain-specific logic beyond orphan detection.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.orphan.detect 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 NoteOrphanDetectInput {
+  flags: Record<string, unknown>;
+}
+
+export interface OrphanReport {
+  file: string;
+  inboundLinks: 0;
+  severity: "warning";
+}
+
+export interface NoteOrphanDetectResult {
+  command: "note.orphan.detect";
+  orphans: OrphanReport[];
+  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 runNoteOrphanDetect(
+  input: NoteOrphanDetectInput,
+  context: { workspaceRoot?: string },
+): ForgeCommandResult<NoteOrphanDetectResult> {
+  const workspaceRoot = context.workspaceRoot ?? process.cwd();
+  const vaultDir = (input.flags["vault-dir"] as string) ?? "vault";
+  const scanDir = path.join(workspaceRoot, vaultDir);
+
+  if (!fs.existsSync(scanDir)) {
+    return {
+      data: {
+        command: "note.orphan.detect",
+        orphans: [],
+        count: 0,
+      },
+      exitCode: 0,
+      summary: "note.orphan.detect: vault directory not found — 0 orphans",
+    };
+  }
+
+  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 inboundLinks = new Map<string, number>();
+  for (const mdFile of allMdFiles) {
+    inboundLinks.set(mdFile, 0);
+  }
+
+  const linkRegex = /\[\[([^\]]+?)\]\]/g;
+  for (const file of allMdFiles) {
+    const fullPath = path.join(workspaceRoot, file);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      let match: RegExpExecArray | null;
+      linkRegex.lastIndex = 0;
+      while ((match = linkRegex.exec(content)) !== null) {
+        const linkTarget = match[1].split("|")[0].split("#")[0].trim();
+        if (!linkTarget) continue;
+        const targetFile = noteMap.get(linkTarget);
+        if (targetFile && targetFile !== file) {
+          inboundLinks.set(targetFile, (inboundLinks.get(targetFile) ?? 0) + 1);
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const orphans: OrphanReport[] = [];
+  for (const [file, count] of inboundLinks) {
+    if (count === 0) {
+      orphans.push({
+        file,
+        inboundLinks: 0,
+        severity: "warning",
+      });
+    }
+  }
+
+  return {
+    data: {
+      command: "note.orphan.detect",
+      orphans,
+      count: orphans.length,
+    },
+    exitCode: 0,
+    summary:
+      orphans.length > 0
+        ? `note.orphan.detect: ${orphans.length} orphan(s) found`
+        : "note.orphan.detect: OK — 0 orphans",
+  };
+}

package/src/validators/port-validate.ts

@@ -0,0 +1,97 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.port.validate — validates that a ported skill or command complies with forge contracts (frontmatter, registry, no project-specific dependencies).</purpose>
+<non-goals>
+  <item>Do not validate all skills — only the named skill or command.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial forge.port.validate handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { FORGE_SKILLS } from "../registry.ts";
+
+interface PortValidateResult {
+  command: string;
+  status: "pass" | "fail";
+  violations: string[];
+}
+
+// RFC-0556: removed @warpgogol/site-kernel-checks and @warpgogol/site-kernel-handoff
+// from this list — os/compass and os/werkstatt no longer import them (handlers inlined).
+// RFC-0776: @warpgogol/site-kernel replaced by @warpgogol/werkstatt/kernel.
+// @warpgogol/werkstatt/kernel remains forbidden for src/ portability.
+const FORBIDDEN_IMPORTS = [
+  "@warpgogol/werkstatt/kernel",
+  "@warpgogol/werkstatt-site/ui",
+  "@warpgogol/werkstatt-shared/share/page",
+];
+
+export function runPortValidate(
+  input: { flags: { name?: string } },
+  context: unknown,
+): PortValidateResult {
+  const ctx = context as { workspaceRoot?: string };
+  const workspaceRoot = ctx?.workspaceRoot ?? process.cwd();
+  const forgeRoot = path.join(workspaceRoot, "packages", "forge");
+  const name = input.flags?.name;
+
+  if (!name) {
+    return {
+      command: "forge.port.validate",
+      status: "fail",
+      violations: ["--name flag is required"],
+    };
+  }
+
+  const violations: string[] = [];
+
+  // Check if skill exists in registry
+  const skillEntry = FORGE_SKILLS.find((s) => s.name === name);
+  if (!skillEntry) {
+    violations.push(`Skill "${name}" not found in forge registry`);
+  }
+
+  // Check for forbidden imports in TypeScript files under the skill/command directory
+  const skillDir = path.join(forgeRoot, "skills");
+  const searchDirs = [
+    path.join(skillDir, "fo", name),
+    path.join(skillDir, "shared", name),
+    path.join(skillDir, "meta", name),
+    path.join(forgeRoot, "os"),
+  ];
+
+  for (const dir of searchDirs) {
+    if (fs.existsSync(dir)) {
+      scanForForbiddenImports(dir, FORBIDDEN_IMPORTS, violations);
+    }
+  }
+
+  return {
+    command: "forge.port.validate",
+    status: violations.length === 0 ? "pass" : "fail",
+    violations,
+  };
+}
+
+function scanForForbiddenImports(dir: string, forbidden: string[], violations: string[]): void {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      scanForForbiddenImports(fullPath, forbidden, violations);
+    } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".mjs")) {
+      const content = fs.readFileSync(fullPath, "utf8");
+      for (const imp of forbidden) {
+        if (content.includes(imp)) {
+          violations.push(
+            `Forbidden import "${imp}" found in ${path.relative(process.cwd(), fullPath)}`,
+          );
+        }
+      }
+    }
+  }
+}