skillwiki 0.2.0-beta.13 → 0.2.0-beta.15

package/dist/cli.js

@@ -67,7 +67,8 @@ var ExitCode = {
   ARCHIVE_TARGET_NOT_FOUND: 30,
   ARCHIVE_ALREADY_ARCHIVED: 31,
   DRIFT_DETECTED: 32,
-  RAW_DEDUP_DETECTED: 33
+  RAW_DEDUP_DETECTED: 33,
+  MIGRATION_APPLIED: 34
 };
 
 // ../shared/src/json-output.ts
@@ -107,10 +108,10 @@ var TypedKnowledgeSchema = z.object({
 });
 var sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
 var RawSourceSchema = z.object({
-  title: z.string().min(1),
-  source_url: z.string().url().nullable(),
+  title: z.string().min(1).optional(),
+  source_url: z.string().nullable(),
   ingested: isoDate,
-  ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]),
+  ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]).optional(),
   sha256: sha256Hex,
   project: wikilink.optional(),
   work_item: wikilink.optional(),
@@ -704,16 +705,46 @@ import { dirname as dirname3, resolve, join as join3 } from "path";
 
 // src/parsers/citations.ts
 var FENCE2 = /```[\s\S]*?```/g;
+var MARKER_RE = /\^\[(raw\/[^\]]+)\]/g;
+function stripFences(body) {
+  return body.replace(FENCE2, "");
+}
 function extractCitationMarkers(body) {
-  const stripped = body.replace(FENCE2, "");
+  const stripped = stripFences(body);
   const out = [];
-  const re = /\^\[(raw\/[^\]]+)\]/g;
   let m;
-  while ((m = re.exec(stripped)) !== null) {
+  while ((m = MARKER_RE.exec(stripped)) !== null) {
     out.push({ marker: m[0], target: m[1] });
   }
   return out;
 }
+function hasSourcesFooter(body) {
+  return /^## Sources\s*$/m.test(stripFences(body));
+}
+function isLegacyCitationStyle(body) {
+  const markers = extractCitationMarkers(body);
+  if (markers.length === 0) return false;
+  if (!hasSourcesFooter(body)) return true;
+  const lines = stripFences(body).split("\n");
+  let inSources = false;
+  for (const line of lines) {
+    if (/^## Sources\b/.test(line.trim())) {
+      inSources = true;
+      continue;
+    }
+    if (inSources) continue;
+    const markerOnly = line.replace(MARKER_RE, "").trim();
+    if (markerOnly.length === 0 && /\^\[raw\//.test(line)) return true;
+    const lastMarkerIdx = line.lastIndexOf("^[raw/");
+    if (lastMarkerIdx >= 0) {
+      const afterLast = line.slice(lastMarkerIdx).replace(MARKER_RE, "").trim();
+      if (afterLast.length > 0) return true;
+      const beforeFirst = line.slice(0, line.indexOf("^[raw/")).trim();
+      if (beforeFirst.length > 0 && !/[.!?]\s*$/.test(beforeFirst)) return true;
+    }
+  }
+  return false;
+}
 
 // src/commands/audit.ts
 async function runAudit(input) {
@@ -743,19 +774,35 @@ async function runAudit(input) {
   const unused_sources = sources.filter((s) => !referenced.has(s));
   const missing_from_sources = [...referenced].filter((t) => !sources.includes(t));
   const broken = resolved.filter((m) => !m.resolved);
+  const footerMatch = body.match(/\n## Sources\n([\s\S]*)$/);
+  let footer_consistency;
+  if (footerMatch) {
+    const footerTargets = /* @__PURE__ */ new Set();
+    const footerRe = /\^\[(raw\/[^\]]+)\]/g;
+    let mm;
+    while ((mm = footerRe.exec(footerMatch[1])) !== null) footerTargets.add(mm[1]);
+    const bodyTargets = new Set(resolved.map((m) => m.target));
+    const missing_from_footer = [...bodyTargets].filter((t) => !footerTargets.has(t));
+    const extra_in_footer = [...footerTargets].filter((t) => !bodyTargets.has(t));
+    footer_consistency = { missing_from_footer, extra_in_footer };
+  }
   const hintLines = [];
   hintLines.push(`markers: ${resolved.length}, broken: ${broken.length}`);
   if (unused_sources.length > 0) hintLines.push(`unused_sources: ${unused_sources.length}`);
   if (missing_from_sources.length > 0) hintLines.push(`missing_from_sources: ${missing_from_sources.length}`);
+  if (footer_consistency) {
+    if (footer_consistency.missing_from_footer.length > 0) hintLines.push(`missing_from_footer: ${footer_consistency.missing_from_footer.length}`);
+    if (footer_consistency.extra_in_footer.length > 0) hintLines.push(`extra_in_footer: ${footer_consistency.extra_in_footer.length}`);
+  }
   if (broken.length === 0 && unused_sources.length === 0 && missing_from_sources.length === 0) hintLines.push("OK");
   const humanHint = hintLines.join("\n");
   if (resolved.some((m) => !m.resolved)) {
-    return { exitCode: ExitCode.UNRESOLVED_MARKERS, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, humanHint }) };
+    return { exitCode: ExitCode.UNRESOLVED_MARKERS, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, footer_consistency, humanHint }) };
   }
   if (unused_sources.length > 0 || missing_from_sources.length > 0) {
-    return { exitCode: ExitCode.SOURCES_INCONSISTENT, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, humanHint }) };
+    return { exitCode: ExitCode.SOURCES_INCONSISTENT, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, footer_consistency, humanHint }) };
   }
-  return { exitCode: ExitCode.OK, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, humanHint }) };
+  return { exitCode: ExitCode.OK, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, footer_consistency, humanHint }) };
 }
 async function findVaultRoot(start) {
   let cur = start;
@@ -1429,7 +1476,7 @@ async function runDedup(input) {
 
 // src/commands/lint.ts
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "contested", "orphans"];
+var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "contested", "orphans", "legacy_citation_style"];
 var INFO_ORDER = ["bridges", "low_confidence_single_source", "topic_map_recommended"];
 async function runLint(input) {
   const buckets = {};
@@ -1473,6 +1520,17 @@ async function runLint(input) {
   }
   const dedup = await runDedup({ vault: input.vault });
   if (dedup.result.ok && dedup.result.data.duplicates.length > 0) buckets.raw_dedup = dedup.result.data.duplicates;
+  const scan = await scanVault(input.vault);
+  if (scan.ok) {
+    const legacyPages = [];
+    for (const page of scan.data.typedKnowledge) {
+      const text = await readPage(page);
+      const split = splitFrontmatter(text);
+      if (!split.ok) continue;
+      if (isLegacyCitationStyle(split.data.body)) legacyPages.push(page.relPath);
+    }
+    if (legacyPages.length > 0) buckets.legacy_citation_style = legacyPages;
+  }
   const errorOut = ERROR_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const warningOut = WARNING_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const infoOut = INFO_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
@@ -1796,6 +1854,151 @@ async function runDrift(input) {
   };
 }
 
+// src/commands/migrate-citations.ts
+import { writeFile as writeFile7 } from "fs/promises";
+var MARKER_RE2 = /\^\[(raw\/[^\]]+)\]/g;
+function moveMarkersToParagraphEnd(body) {
+  const lines = body.split("\n");
+  const result = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trimStart().startsWith("```")) {
+      result.push(line);
+      if (!line.trimEnd().endsWith("```") || line.trim() === "```") {
+        for (let j = i + 1; j < lines.length; j++) {
+          result.push(lines[j]);
+          if (lines[j].trimStart().startsWith("```")) {
+            i = j;
+            break;
+          }
+        }
+      }
+      continue;
+    }
+    if (/^## Sources\b/.test(line.trim())) {
+      result.push(line);
+      continue;
+    }
+    const markers = [...line.matchAll(MARKER_RE2)];
+    if (markers.length === 0) {
+      result.push(line);
+      continue;
+    }
+    const proseOnly = line.replace(MARKER_RE2, "").trim();
+    if (proseOnly.length === 0) {
+      const markerStr = " " + markers.map((m) => m[0]).join(" ");
+      let merged = false;
+      for (let k = result.length - 1; k >= 0; k--) {
+        if (result[k].trim().length > 0) {
+          result[k] = result[k].trimEnd() + markerStr;
+          merged = true;
+          break;
+        }
+      }
+      if (!merged) result.push(line);
+      continue;
+    }
+    const lastMarkerIdx = line.lastIndexOf("^[raw/");
+    const afterLast = line.slice(lastMarkerIdx).replace(MARKER_RE2, "").trim();
+    const firstMarkerIdx = line.indexOf("^[raw/");
+    const beforeFirst = line.slice(0, firstMarkerIdx).trim();
+    const alreadyAtEnd = afterLast.length === 0 && (beforeFirst.length === 0 || /[.!?]\s*$/.test(beforeFirst));
+    if (alreadyAtEnd) {
+      result.push(line);
+      continue;
+    }
+    let cleaned = line.replace(/\s*\^\[raw\/[^\]]+\]\s*/g, " ").trimEnd();
+    cleaned = cleaned.replace(/  +/g, " ").trimEnd();
+    const markerStrings = markers.map((m) => m[0]);
+    if (cleaned.length > 0 && /[.!?]$/.test(cleaned)) {
+      cleaned += " " + markerStrings.join(" ");
+    } else if (cleaned.length > 0) {
+      cleaned += ". " + markerStrings.join(" ");
+    } else {
+      cleaned = markerStrings.join(" ");
+    }
+    result.push(cleaned);
+  }
+  return result.join("\n");
+}
+function buildSourcesFooter(targets) {
+  return "\n## Sources\n" + targets.map((t) => `- ^[${t}]`).join("\n") + "\n";
+}
+function reorderSourcesFm(rawFm, targets) {
+  const sourcesLineRe = /^sources:\s*\[([^\]]*)\]\s*$/m;
+  const match = rawFm.match(sourcesLineRe);
+  if (!match) return rawFm;
+  const existing = match[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter((s) => s.length > 0);
+  const targetSet = new Set(targets);
+  const reordered = [
+    ...targets,
+    ...existing.filter((s) => !targetSet.has(s))
+  ];
+  const newLine = `sources: [${reordered.join(", ")}]`;
+  return rawFm.replace(sourcesLineRe, newLine);
+}
+function removeExistingFooter(body) {
+  const footerRe = /\n## Sources\n[\s\S]*$/;
+  return body.replace(footerRe, "");
+}
+async function runMigrateCitations(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const migrated = [];
+  const skipped = [];
+  let unchanged = 0;
+  for (const page of scan.data.typedKnowledge) {
+    const text = await readPage(page);
+    const split = splitFrontmatter(text);
+    if (!split.ok) continue;
+    const { rawFrontmatter, body } = split.data;
+    const markers = extractCitationMarkers(body);
+    if (markers.length === 0) {
+      unchanged++;
+      continue;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const uniqueTargets = [];
+    for (const m of markers) {
+      if (!seen.has(m.target)) {
+        seen.add(m.target);
+        uniqueTargets.push(m.target);
+      }
+    }
+    const bodyWithoutFooter = removeExistingFooter(body);
+    const migratedBody = moveMarkersToParagraphEnd(bodyWithoutFooter);
+    const newFooter = buildSourcesFooter(uniqueTargets);
+    const newFm = reorderSourcesFm(rawFrontmatter, uniqueTargets);
+    const newText = `---
+${newFm}
+---
+${migratedBody}${newFooter}`;
+    if (newText === text) {
+      skipped.push(page.relPath);
+      continue;
+    }
+    if (!input.dryRun) {
+      await writeFile7(page.absPath, newText, "utf8");
+    }
+    migrated.push(page.relPath);
+  }
+  const exitCode = migrated.length > 0 ? ExitCode.MIGRATION_APPLIED : ExitCode.OK;
+  const hintLines = [`scanned: ${migrated.length + skipped.length + unchanged}`];
+  if (migrated.length > 0) hintLines.push(`migrated: ${migrated.length}`);
+  if (skipped.length > 0) hintLines.push(`skipped (already clean): ${skipped.length}`);
+  if (unchanged > 0) hintLines.push(`unchanged (no markers): ${unchanged}`);
+  return {
+    exitCode,
+    result: ok({
+      scanned: migrated.length + skipped.length + unchanged,
+      migrated,
+      skipped,
+      unchanged,
+      humanHint: hintLines.join("\n")
+    })
+  };
+}
+
 // src/cli.ts
 var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
@@ -1931,6 +2134,11 @@ program.command("dedup [vault]").description("detect duplicate raw sources by sh
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runDedup({ vault: v.vault }));
 });
+program.command("migrate-citations [vault]").description("migrate ^[raw/...] markers to paragraph-end citations").option("--dry-run", "preview changes without writing", false).action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runMigrateCitations({ vault: v.vault, dryRun: !!opts.dryRun }));
+});
 program.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.13",
+  "version": "0.2.0-beta.15",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.13",
+  "version": "0.2.0-beta.15",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 11 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
   "author": {

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.0-beta.13",
+  "version": "0.2.0-beta.15",
   "private": true,
   "files": [
     "wiki-*",

package/templates/SCHEMA.md

@@ -49,7 +49,8 @@ Rule: every tag on every page MUST appear in this taxonomy. Add new tags here fi
 
 - File names: lowercase-hyphenated, no spaces.
 - Wikilinks in YAML: quoted, `"[[name]]"`. Body wikilinks: unquoted `[[name]]`.
-- Citations in body: `^[raw/...]` markers; every entry in `sources:` MUST appear in body.
+- Citations in body: `^[raw/...]` markers at paragraph-end; every entry in `sources:` MUST appear in body and in `## Sources` footer.
+- Legacy inline `^[raw/...]` markers remain valid; `migrate-citations` converts them.
 - sha256 in `raw/` frontmatter is computed by `skillwiki hash` over body bytes after closing `---`.
 
 ## Obsidian Integration