sdtk-wiki-kit 0.1.0 → 0.1.2

package/src/lib/wiki-extract.js

@@ -0,0 +1,637 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { CliError, ValidationError } = require("./errors");
+const {
+  assertWikiWorkspaceWritePath,
+  getWikiReportsPath,
+  resolveProjectPath,
+} = require("./wiki-paths");
+
+const REPORT_PREFIX = "semantic-extraction-dry-run";
+const SCHEMA_VERSION = 1;
+const EXCLUDE_FRAGS = [
+  ".git",
+  ".sdtk/wiki",
+  ".sdtk/atlas",
+  "node_modules",
+  ".venv",
+  "venv",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  "__pycache__",
+];
+
+const CONCEPT_RULES = [
+  {
+    concept_id: "concept_self_hosted_project_management",
+    name: "self-hosted project management",
+    aliases: ["Trello alternative", "realtime collaboration", "project management"],
+    keywords: ["trello", "jira", "project management", "realtime collaboration", "collaboration"],
+    category: "project_management",
+  },
+  {
+    concept_id: "concept_agent_skills",
+    name: "agent skills",
+    aliases: ["AI agent skills", "skill pack", "coding agent skills"],
+    keywords: ["skill", "skills", "agent", "claude code", "codex", "cursor", "gemini"],
+    category: "agent_skills",
+  },
+  {
+    concept_id: "concept_secret_scanning",
+    name: "secret scanning",
+    aliases: ["API key detection", "token detection", "credential scanning"],
+    keywords: ["gitleaks", "secret", "token", "password", "api key"],
+    category: "secret_scanning",
+  },
+  {
+    concept_id: "concept_self_hosted_local_first_tools",
+    name: "self-hosted local-first tools",
+    aliases: ["local-first", "privacy", "self-hosted"],
+    keywords: ["self-hosted", "local", "privacy", "offline"],
+    category: "local_first_privacy",
+  },
+  {
+    concept_id: "concept_ai_media_generation",
+    name: "AI media generation",
+    aliases: ["AI video", "AI music", "generative media"],
+    keywords: ["video", "music", "suno", "lipdub", "comfyui", "ace-step"],
+    category: "ai_media",
+  },
+  {
+    concept_id: "concept_document_management",
+    name: "document management",
+    aliases: ["paperless", "PDF workflow", "document archive"],
+    keywords: ["paperless", "document", "pdf", "ocr", "archive"],
+    category: "document_management",
+  },
+  {
+    concept_id: "concept_developer_tooling",
+    name: "developer tooling",
+    aliases: ["open source developer tool", "CLI", "framework"],
+    keywords: ["github", "repo", "open-source", "mã nguồn", "cli", "framework", "developer"],
+    category: "developer_tooling",
+  },
+];
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function isRemoteUrl(value) {
+  return /^(?:https?|ftp):\/\//i.test(String(value || ""));
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex");
+}
+
+function timestampStamp(date = new Date()) {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z").replace("T", "-");
+}
+
+function safeSlug(value, fallback = "item") {
+  const slug = String(value || "")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/https?:\/\/\S+/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-+/g, "-")
+    .slice(0, 64)
+    .replace(/^-+|-+$/g, "");
+  return slug || fallback;
+}
+
+function normaliseExcludeFragment(frag) {
+  return toPosix(frag).replace(/^\/+|\/+$/g, "").toLowerCase().split("/").filter(Boolean);
+}
+
+function isExcluded(targetPath, sourceRoot) {
+  const relative = toPosix(path.relative(sourceRoot, targetPath)).toLowerCase();
+  const parts = relative.split("/").filter((part) => part && part !== ".");
+  for (const frag of EXCLUDE_FRAGS) {
+    const fragParts = normaliseExcludeFragment(frag);
+    if (fragParts.length === 0) continue;
+    if (fragParts.length === 1) {
+      if (parts.includes(fragParts[0])) return `exclude:${frag}`;
+      continue;
+    }
+    for (let idx = 0; idx <= parts.length - fragParts.length; idx += 1) {
+      if (parts.slice(idx, idx + fragParts.length).join("/") === fragParts.join("/")) {
+        return `exclude:${frag}`;
+      }
+    }
+  }
+  return null;
+}
+
+function collectMarkdownFiles(sourceRoot) {
+  const files = [];
+  const skipped = [];
+  let scanned = 0;
+
+  function visit(current) {
+    const stat = fs.statSync(current);
+    if (stat.isDirectory()) {
+      const excluded = isExcluded(current, sourceRoot);
+      if (excluded) return;
+      for (const child of fs.readdirSync(current).sort()) {
+        visit(path.join(current, child));
+      }
+      return;
+    }
+    if (!stat.isFile()) return;
+    if (!/\.md(?:arkdown)?$/i.test(current)) return;
+    scanned += 1;
+    const excluded = isExcluded(current, sourceRoot);
+    if (excluded) {
+      skipped.push({
+        path: toPosix(path.relative(sourceRoot, current)),
+        reason: excluded,
+      });
+      return;
+    }
+    files.push(current);
+  }
+
+  const stat = fs.statSync(sourceRoot);
+  if (stat.isFile()) {
+    scanned += /\.md(?:arkdown)?$/i.test(sourceRoot) ? 1 : 0;
+    if (/\.md(?:arkdown)?$/i.test(sourceRoot)) files.push(sourceRoot);
+  } else {
+    visit(sourceRoot);
+  }
+
+  return { files: files.sort((a, b) => toPosix(a).localeCompare(toPosix(b))), skipped, scanned };
+}
+
+function parseFrontmatterTitle(text) {
+  const lines = text.split(/\r?\n/);
+  if (!lines.length || lines[0].trim() !== "---") return "";
+  for (let idx = 1; idx < lines.length; idx += 1) {
+    const line = lines[idx];
+    if (line.trim() === "---") break;
+    const match = line.match(/^title:\s*(.+?)\s*$/i);
+    if (match) return match[1].trim().replace(/^["']|["']$/g, "");
+  }
+  return "";
+}
+
+function extractTitle(text, filePath) {
+  const frontmatterTitle = parseFrontmatterTitle(text);
+  if (frontmatterTitle) return frontmatterTitle;
+  const heading = text.match(/^#\s+(.+?)\s*$/m);
+  if (heading) return heading[1].trim();
+  return path.basename(filePath, path.extname(filePath)).replace(/[_-]+/g, " ").trim();
+}
+
+function detectMojibake(text) {
+  const matches = text.match(/�|Ã.|Â.|â€|ðŸ/gi) || [];
+  return {
+    hasMojibake: matches.length > 0,
+    score: Math.min(1, matches.length / Math.max(1, text.length / 500)),
+  };
+}
+
+function extractGithubRepos(text) {
+  const repos = [];
+  const seen = new Set();
+  const githubRegex = /(?:https?:\/\/)?(?:www\.)?github\.com\/([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]+)/gi;
+  let match;
+  while ((match = githubRegex.exec(text)) !== null) {
+    const owner = match[1];
+    const rawRepo = match[2].replace(/[).,;:]+$/g, "");
+    if (!rawRepo || rawRepo === "..." || rawRepo.includes("...")) continue;
+    const repo = rawRepo.replace(/\.git$/i, "");
+    const key = `${owner.toLowerCase()}/${repo.toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    repos.push({
+      owner,
+      repo,
+      github_url: `https://github.com/${owner}/${repo}`,
+      key,
+    });
+  }
+  return repos;
+}
+
+function extractUnsupportedGithubItems(text) {
+  const items = [];
+  const invalidRegex = /github\.com\/(?:\.\.\.|[^\s)]+\.{3}[^\s)]*)/gi;
+  let match;
+  while ((match = invalidRegex.exec(text)) !== null) {
+    items.push(match[0]);
+  }
+  return [...new Set(items)];
+}
+
+function inferConcepts(text) {
+  const lower = text.toLowerCase();
+  return CONCEPT_RULES.filter((rule) => rule.keywords.some((keyword) => lower.includes(keyword.toLowerCase())));
+}
+
+function categoryForSource(text, concepts) {
+  if (concepts.length > 0) return concepts[0].category;
+  const lower = text.toLowerCase();
+  if (lower.includes("github") || lower.includes("repo")) return "developer_tooling";
+  return "uncategorized";
+}
+
+function confidenceTier(confidence) {
+  if (confidence >= 0.8) return "high";
+  if (confidence >= 0.5) return "medium";
+  if (confidence >= 0.2) return "low";
+  return "unsupported";
+}
+
+function makeSourceRootRef(sourceRoot) {
+  const display = toPosix(sourceRoot);
+  const label = safeSlug(path.basename(sourceRoot), "source-root");
+  return {
+    source_root_id: `root_${sha256(`source-root:v1:${display.toLowerCase()}`).slice(0, 12)}`,
+    source_root_label: label,
+    source_root_type: "external_local",
+    source_root_display_path: display,
+    normalization_version: "source-root:v1",
+  };
+}
+
+function buildProvenance({ sourceId, sourceHash, sourceRelativePath, sourceLogicalPath, line, generatedAt, confidence }) {
+  return {
+    provenance_id: `prov_${sourceId}_${String(line || 1).padStart(3, "0")}`,
+    source_id: sourceId,
+    source_hash: sourceHash,
+    source_relative_path: sourceRelativePath,
+    source_logical_path: sourceLogicalPath,
+    locator: {
+      type: "line_range",
+      start_line: line || 1,
+      end_line: line || 1,
+      heading: null,
+    },
+    evidence_quote_hash: sha256(`${sourceId}:${line || 1}`),
+    extractor: "sdtk-wiki.semantic-extract",
+    extractor_version: "bk132-dry-run",
+    generated_at: generatedAt,
+    confidence,
+  };
+}
+
+function lineOf(text, needle) {
+  const idx = text.indexOf(needle);
+  if (idx < 0) return 1;
+  return text.slice(0, idx).split(/\r?\n/).length;
+}
+
+function buildExtraction({ projectPath, sourceRoot }) {
+  const generatedAt = new Date().toISOString();
+  const sourceRootRef = makeSourceRootRef(sourceRoot);
+  const collected = collectMarkdownFiles(sourceRoot);
+  const sources = [];
+  const toolEntitiesById = new Map();
+  const conceptsById = new Map();
+  const claims = [];
+  const relations = [];
+  const provenance = [];
+  const sourceQualityFindings = [];
+  const unsupportedItems = [];
+  const sourceUrlUsage = new Map();
+
+  for (const filePath of collected.files) {
+    const text = fs.readFileSync(filePath, "utf-8");
+    const sourceHash = sha256(fs.readFileSync(filePath));
+    const stats = fs.statSync(filePath);
+    const sourceRelativePath = toPosix(path.relative(sourceRoot, filePath));
+    const sourceLogicalPath = `${sourceRootRef.source_root_label}/${sourceRelativePath}`;
+    const sourceDisplayPath = toPosix(filePath);
+    const sourceId = `src_${sha256(`local-md:v1:${sourceRootRef.source_root_id}:${sourceRelativePath.toLowerCase()}`).slice(0, 16)}`;
+    const title = extractTitle(text, filePath);
+    const repos = extractGithubRepos(text);
+    const unsupportedGithub = extractUnsupportedGithubItems(text);
+    const concepts = inferConcepts(`${title}\n${text}`);
+    const category = categoryForSource(`${title}\n${text}`, concepts);
+    const mojibake = detectMojibake(text);
+    const weakTitle = title.length < 6 || /^untitled|note|readme$/i.test(title);
+    const sourceUrl = repos.length > 0 ? repos[0].github_url : null;
+    const sourceSlug = `${safeSlug(title || sourceRelativePath, "source")}--${sourceId.slice(0, 8)}`;
+    const qualityFlags = [];
+    const qualityNotes = [];
+
+    if (mojibake.hasMojibake) {
+      qualityFlags.push("mojibake_detected");
+      qualityNotes.push("Potential mojibake or replacement characters detected.");
+    }
+    if (!sourceUrl) {
+      qualityFlags.push("missing_source_url");
+      qualityNotes.push("No valid GitHub/source URL was extracted.");
+    }
+    if (weakTitle) {
+      qualityFlags.push("weak_title");
+      qualityNotes.push("Title is missing, very short, or generic.");
+    }
+    if (repos.length === 0) {
+      qualityFlags.push("low_confidence_extraction");
+    }
+
+    const sourceRecord = {
+      source_id: sourceId,
+      source_root_id: sourceRootRef.source_root_id,
+      source_relative_path: sourceRelativePath,
+      source_logical_path: sourceLogicalPath,
+      source_display_path: sourceDisplayPath,
+      source_type: "markdown",
+      title,
+      source_url: sourceUrl,
+      source_hash: sourceHash,
+      size_bytes: stats.size,
+      modified_time: stats.mtime.toISOString(),
+      encoding_quality: mojibake.hasMojibake ? "suspect" : "clean",
+      source_quality: {
+        has_mojibake: mojibake.hasMojibake,
+        mojibake_score: Number(mojibake.score.toFixed(3)),
+        has_source_url: Boolean(sourceUrl),
+        weak_title: weakTitle,
+        duplicate_candidate: false,
+        duplicate_group_id: null,
+        low_confidence_extraction: repos.length === 0,
+        quality_flags: qualityFlags,
+        notes: qualityNotes,
+      },
+      provenance_refs: [],
+      target_page_path: `.sdtk/wiki/personal-brain/sources/${sourceSlug}.md`,
+    };
+
+    sources.push(sourceRecord);
+
+    if (sourceUrl) {
+      const existing = sourceUrlUsage.get(sourceUrl) || [];
+      existing.push(sourceRecord);
+      sourceUrlUsage.set(sourceUrl, existing);
+    }
+
+    for (const rawUnsupported of unsupportedGithub) {
+      unsupportedItems.push({
+        record_type: "unsupported_item",
+        item_id: `unsupported_${sourceId}_${String(unsupportedItems.length + 1).padStart(3, "0")}`,
+        source_id: sourceId,
+        reason: "unsupported_url_format",
+        raw_observation_summary: rawUnsupported,
+        confidence: 0.1,
+        confidence_tier: "unsupported",
+        provenance_refs: [],
+      });
+      if (!qualityFlags.includes("unsupported_url_format")) {
+        sourceRecord.source_quality.quality_flags.push("unsupported_url_format");
+      }
+    }
+
+    if (qualityFlags.length > 0) {
+      sourceQualityFindings.push({
+        finding_id: `sq_${sourceId}`,
+        source_id: sourceId,
+        source_relative_path: sourceRelativePath,
+        source_logical_path: sourceLogicalPath,
+        quality_flags: [...sourceRecord.source_quality.quality_flags],
+        confidence: repos.length === 0 ? 0.3 : 0.7,
+        confidence_tier: repos.length === 0 ? "low" : "medium",
+        notes: qualityNotes,
+      });
+    }
+
+    for (const repo of repos) {
+      const entityId = `tool_github_${safeSlug(repo.owner, "owner")}_${safeSlug(repo.repo, "repo")}`;
+      const prov = buildProvenance({
+        sourceId,
+        sourceHash,
+        sourceRelativePath,
+        sourceLogicalPath,
+        line: lineOf(text, repo.github_url),
+        generatedAt,
+        confidence: 0.9,
+      });
+      provenance.push(prov);
+      sourceRecord.provenance_refs.push(prov.provenance_id);
+
+      if (!toolEntitiesById.has(entityId)) {
+        toolEntitiesById.set(entityId, {
+          entity_id: entityId,
+          entity_type: "tool_entity",
+          name: repo.repo,
+          repo_owner: repo.owner,
+          repo_name: repo.repo,
+          github_url: repo.github_url,
+          category,
+          summary: `${repo.repo} is a locally sourced GitHub tool candidate in category ${category}.`,
+          confidence: 0.9,
+          confidence_tier: "high",
+          source_refs: [],
+          provenance_refs: [],
+          target_page_path: `.sdtk/wiki/personal-brain/entities/tools/${safeSlug(repo.repo, "tool")}--${entityId}.md`,
+        });
+      }
+      const entity = toolEntitiesById.get(entityId);
+      if (!entity.source_refs.includes(sourceId)) entity.source_refs.push(sourceId);
+      if (!entity.provenance_refs.includes(prov.provenance_id)) entity.provenance_refs.push(prov.provenance_id);
+
+      claims.push({
+        claim_id: `claim_${sourceId}_${String(claims.length + 1).padStart(3, "0")}`,
+        text: `The local source presents ${repo.repo} as a ${category} tool or project.`,
+        subject_entity_id: entityId,
+        source_refs: [sourceId],
+        provenance_refs: [prov.provenance_id],
+        confidence: 0.75,
+        confidence_tier: "medium",
+        contested: false,
+      });
+
+      relations.push({
+        relation_id: `rel_${sourceId}_${String(relations.length + 1).padStart(3, "0")}`,
+        source_id: sourceId,
+        target_id: entityId,
+        relation_type: "source_mentions_entity",
+        evidence: "The local Markdown source includes a GitHub repository URL.",
+        source_refs: [sourceId],
+        provenance_refs: [prov.provenance_id],
+        confidence: 0.9,
+        confidence_tier: "high",
+      });
+    }
+
+    for (const conceptRule of concepts) {
+      if (!conceptsById.has(conceptRule.concept_id)) {
+        conceptsById.set(conceptRule.concept_id, {
+          concept_id: conceptRule.concept_id,
+          name: conceptRule.name,
+          aliases: conceptRule.aliases,
+          definition: `Local sources contain evidence related to ${conceptRule.name}.`,
+          related_entities: [],
+          source_refs: [],
+          provenance_refs: [],
+          confidence: 0.65,
+          confidence_tier: "medium",
+          target_page_path: `.sdtk/wiki/personal-brain/concepts/${safeSlug(conceptRule.name, "concept")}.md`,
+        });
+      }
+      const concept = conceptsById.get(conceptRule.concept_id);
+      if (!concept.source_refs.includes(sourceId)) concept.source_refs.push(sourceId);
+
+      for (const repo of repos) {
+        const entityId = `tool_github_${safeSlug(repo.owner, "owner")}_${safeSlug(repo.repo, "repo")}`;
+        if (!concept.related_entities.includes(entityId)) concept.related_entities.push(entityId);
+        relations.push({
+          relation_id: `rel_${sourceId}_${String(relations.length + 1).padStart(3, "0")}`,
+          source_id: entityId,
+          target_id: conceptRule.concept_id,
+          relation_type: "entity_implements_concept",
+          evidence: `The local source text matches ${conceptRule.name} keywords.`,
+          source_refs: [sourceId],
+          provenance_refs: [...sourceRecord.provenance_refs],
+          confidence: 0.7,
+          confidence_tier: "medium",
+        });
+      }
+    }
+  }
+
+  for (const [sourceUrl, sourceRecords] of sourceUrlUsage.entries()) {
+    if (sourceRecords.length < 2) continue;
+    const duplicateGroupId = `dup_${sha256(sourceUrl).slice(0, 12)}`;
+    for (const record of sourceRecords) {
+      record.source_quality.duplicate_candidate = true;
+      record.source_quality.duplicate_group_id = duplicateGroupId;
+      if (!record.source_quality.quality_flags.includes("duplicate_source_candidate")) {
+        record.source_quality.quality_flags.push("duplicate_source_candidate");
+      }
+      sourceQualityFindings.push({
+        finding_id: `sq_duplicate_${record.source_id}`,
+        source_id: record.source_id,
+        source_relative_path: record.source_relative_path,
+        source_logical_path: record.source_logical_path,
+        quality_flags: ["duplicate_source_candidate"],
+        duplicate_group_id: duplicateGroupId,
+        confidence: 0.8,
+        confidence_tier: "high",
+        notes: [`Duplicate source URL candidate: ${sourceUrl}`],
+      });
+    }
+  }
+
+  const toolEntities = [...toolEntitiesById.values()].sort((a, b) => a.entity_id.localeCompare(b.entity_id));
+  const concepts = [...conceptsById.values()].sort((a, b) => a.concept_id.localeCompare(b.concept_id));
+  const comparisons = [];
+  const syntheses = [];
+
+  for (const concept of concepts) {
+    if (concept.related_entities.length < 2) continue;
+    const topicSlug = safeSlug(concept.name, "topic");
+    comparisons.push({
+      comparison_id: `comparison_${topicSlug}_${sha256(concept.related_entities.join("|")).slice(0, 8)}`,
+      topic: concept.name,
+      compared_entities: concept.related_entities.slice(0, 8),
+      criteria: ["local evidence", "category fit", "source confidence"],
+      source_refs: concept.source_refs,
+      provenance_refs: concept.provenance_refs,
+      confidence: 0.55,
+      confidence_tier: "medium",
+      target_page_path: `.sdtk/wiki/personal-brain/comparisons/${topicSlug}.md`,
+    });
+    syntheses.push({
+      synthesis_id: `synthesis_${topicSlug}_${sha256(concept.source_refs.join("|")).slice(0, 8)}`,
+      topic: concept.name,
+      summary: `Local sources mention ${concept.related_entities.length} tool candidate(s) related to ${concept.name}.`,
+      recommendations: ["Review extracted entities and source quality findings before compile/apply work."],
+      source_refs: concept.source_refs,
+      provenance_refs: concept.provenance_refs,
+      confidence: 0.55,
+      confidence_tier: "medium",
+      target_page_path: `.sdtk/wiki/personal-brain/syntheses/${topicSlug}.md`,
+    });
+  }
+
+  const lowConfidence = sourceQualityFindings.filter((finding) => ["low", "unsupported"].includes(finding.confidence_tier)).length;
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    record_type: "sdtk_wiki_semantic_extraction",
+    generated_at: generatedAt,
+    project_path: projectPath,
+    source_root_refs: [sourceRootRef],
+    source_counts: {
+      scanned: collected.scanned,
+      indexed: sources.length,
+      extracted: toolEntities.length,
+      skipped: collected.skipped.length,
+      low_confidence: lowConfidence,
+      unsupported: unsupportedItems.length,
+    },
+    skipped_sources: collected.skipped,
+    sources,
+    tool_entities: toolEntities,
+    concepts,
+    claims,
+    relations,
+    comparisons,
+    syntheses,
+    source_quality_findings: sourceQualityFindings,
+    unsupported_items: unsupportedItems,
+    provenance,
+  };
+}
+
+function resolveSourceRoot(sourceRootArg) {
+  if (!sourceRootArg) {
+    throw new ValidationError("sdtk-wiki wiki extract requires --source-root <path>. No project files were changed.");
+  }
+  if (isRemoteUrl(sourceRootArg)) {
+    throw new ValidationError("Remote URL source roots are not supported for semantic extraction dry-run. No project files were changed.");
+  }
+  const resolved = path.resolve(sourceRootArg);
+  if (!fs.existsSync(resolved)) {
+    throw new ValidationError(`--source-root does not exist: ${resolved}. No project files were changed.`);
+  }
+  const stat = fs.statSync(resolved);
+  if (!stat.isDirectory() && !stat.isFile()) {
+    throw new ValidationError(`--source-root is not a file or directory: ${resolved}. No project files were changed.`);
+  }
+  return resolved;
+}
+
+function runWikiExtractDryRun({ projectPath, sourceRootArg }) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}`);
+  }
+  const sourceRoot = resolveSourceRoot(sourceRootArg);
+
+  try {
+    const reportsPath = getWikiReportsPath(resolvedProjectPath);
+    assertWikiWorkspaceWritePath(reportsPath, resolvedProjectPath);
+    const extraction = buildExtraction({ projectPath: resolvedProjectPath, sourceRoot });
+    const reportPath = path.join(reportsPath, `${REPORT_PREFIX}-${timestampStamp(new Date(extraction.generated_at))}.json`);
+    assertWikiWorkspaceWritePath(reportPath, resolvedProjectPath);
+    fs.mkdirSync(reportsPath, { recursive: true });
+    fs.writeFileSync(reportPath, JSON.stringify(extraction, null, 2) + "\n", "utf-8");
+    return {
+      reportPath,
+      extraction,
+    };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(`Failed to write SDTK-WIKI semantic extraction dry-run report: ${error.message}`);
+  }
+}
+
+module.exports = {
+  REPORT_PREFIX,
+  buildExtraction,
+  runWikiExtractDryRun,
+};

package/src/lib/wiki-flags.js

@@ -42,11 +42,18 @@ const DISCOVER_FLAG_DEFS = {
   plan: { type: "boolean" },
 };
 
+const EXTRACT_FLAG_DEFS = {
+  "project-path": { type: "string" },
+  "source-root": { type: "string" },
+  "dry-run": { type: "boolean" },
+};
+
 const COMPILE_FLAG_DEFS = {
   "project-path": { type: "string" },
   plan: { type: "string" },
   "dry-run": { type: "boolean" },
   apply: { type: "boolean" },
+  yes: { type: "boolean" },
 };
 
 function parseWikiFlags(args, defs) {
@@ -80,6 +87,7 @@ module.exports = {
   BASE_FLAG_DEFS,
   COMPILE_FLAG_DEFS,
   DISCOVER_FLAG_DEFS,
+  EXTRACT_FLAG_DEFS,
   INIT_FLAG_DEFS,
   LINT_FLAG_DEFS,
   OPEN_FLAG_DEFS,