@topogram/cli 0.3.34

package/src/import/extractors/verification/generic.js

@@ -0,0 +1,290 @@
+import {
+  canonicalCandidateTerm,
+  dedupeCandidateRecords,
+  findImportFiles,
+  idHintify,
+  makeCandidateRecord,
+  normalizeImportRelativePath,
+  pluralizeCandidateTerm,
+  readJsonIfExists,
+  readTextIfExists,
+  slugify,
+  titleCase
+} from "../../core/shared.js";
+
+const JS_TEST_PATTERN = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$/i;
+const PYTHON_TEST_PATTERN = /(^|\/)(test_[^/]+|[^/]+_test)\.py$/i;
+const RUBY_TEST_PATTERN = /(^|\/)[^/]+_spec\.rb$/i;
+const SWIFT_TEST_PATTERN = /(^|\/)[^/]*Tests?\.swift$/i;
+
+function frameworkInfo(context) {
+  const packageFiles = findImportFiles(context.paths, (filePath) => /package\.json$/i.test(filePath));
+  const frameworks = new Set();
+  const scripts = [];
+
+  for (const packagePath of packageFiles) {
+    const pkg = readJsonIfExists(packagePath);
+    if (!pkg) continue;
+    const deps = {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {})
+    };
+    if (deps["@playwright/test"] || deps.playwright) frameworks.add("playwright");
+    if (deps.vitest) frameworks.add("vitest");
+    if (deps.jest) frameworks.add("jest");
+    if (deps.cypress) frameworks.add("cypress");
+
+    for (const [name, command] of Object.entries(pkg.scripts || {})) {
+      if (!/^test($|[-:])/.test(name) && !/(playwright|vitest|jest|cypress|pytest|rspec)/i.test(String(command || ""))) {
+        continue;
+      }
+      scripts.push({
+        name,
+        command,
+        file: normalizeImportRelativePath(context.paths, packagePath)
+      });
+    }
+  }
+
+  const configFiles = findImportFiles(
+    context.paths,
+    (filePath) => /(playwright\.config|vitest\.config|jest\.config|cypress\.config)\.(ts|js|mjs|cjs)$/i.test(filePath)
+  );
+  for (const filePath of configFiles) {
+    const lower = filePath.toLowerCase();
+    if (lower.includes("playwright")) frameworks.add("playwright");
+    if (lower.includes("vitest")) frameworks.add("vitest");
+    if (lower.includes("jest")) frameworks.add("jest");
+    if (lower.includes("cypress")) frameworks.add("cypress");
+  }
+
+  return {
+    frameworks: [...frameworks].sort(),
+    scripts: scripts.sort((left, right) => left.name.localeCompare(right.name) || left.file.localeCompare(right.file))
+  };
+}
+
+function findTestFiles(context) {
+  return findImportFiles(context.paths, (filePath) => {
+    const normalized = filePath.replaceAll("\\", "/");
+    return (
+      JS_TEST_PATTERN.test(normalized) ||
+      PYTHON_TEST_PATTERN.test(normalized) ||
+      RUBY_TEST_PATTERN.test(normalized) ||
+      SWIFT_TEST_PATTERN.test(normalized) ||
+      /\/playwright\/.+\.(ts|tsx|js|jsx)$/i.test(normalized) ||
+      /\/cypress\/.+\.(ts|tsx|js|jsx)$/i.test(normalized)
+    );
+  });
+}
+
+function inferFramework(filePath, frameworks) {
+  const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+  if (normalized.includes("/playwright/")) return "playwright";
+  if (normalized.includes("/cypress/")) return "cypress";
+  if (normalized.endsWith(".py")) return "pytest";
+  if (normalized.endsWith("_spec.rb")) return "rspec";
+  if (normalized.endsWith(".swift")) return "xctest";
+  if (frameworks.includes("vitest")) return "vitest";
+  if (frameworks.includes("jest")) return "jest";
+  return "test";
+}
+
+function inferMethod(filePath, framework) {
+  const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+  if (framework === "playwright" || framework === "cypress") {
+    return normalized.includes("smoke") ? "smoke" : "runtime";
+  }
+  if (normalized.includes("/e2e/") || normalized.includes("/integration/")) {
+    return "runtime";
+  }
+  return "contract";
+}
+
+function extractScenarioTitles(source, filePath) {
+  const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+  const titles = [];
+
+  if (/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(normalized)) {
+    for (const match of source.matchAll(/\b(?:test|it|describe)\(\s*['"`]([^'"`]+)['"`]/g)) {
+      titles.push(match[1]);
+    }
+  } else if (normalized.endsWith(".py")) {
+    for (const match of source.matchAll(/\bdef\s+(test_[a-zA-Z0-9_]+)\s*\(/g)) {
+      titles.push(match[1].replace(/^test_/, "").replaceAll("_", " "));
+    }
+  } else if (normalized.endsWith(".rb")) {
+    for (const match of source.matchAll(/\bit\s+['"]([^'"]+)['"]/g)) {
+      titles.push(match[1]);
+    }
+  } else if (normalized.endsWith(".swift")) {
+    for (const match of source.matchAll(/\bfunc\s+(test[A-Za-z0-9_]+)\s*\(/g)) {
+      titles.push(match[1].replace(/^test/, "").replace(/([A-Z])/g, " $1").trim());
+    }
+  }
+
+  return [...new Set(titles)];
+}
+
+function capabilityMatchers(apiCandidates = []) {
+  return (apiCandidates.capabilities || []).map((capability) => {
+    const entityStem = canonicalCandidateTerm(
+      String(capability.entity_id || capability.id_hint || "").replace(/^entity_/, "").replace(/^cap_[a-z]+_/, "")
+    );
+    const terms = new Set([
+      entityStem,
+      pluralizeCandidateTerm(entityStem),
+      ...String(capability.label || "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean),
+      ...String(capability.id_hint || "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+    ]);
+    return { capability, terms: [...terms].filter(Boolean) };
+  });
+}
+
+function inferRelatedCapabilities(text, matchers) {
+  const normalized = ` ${String(text || "").toLowerCase().replace(/[^a-z0-9]+/g, " ")} `;
+  return matchers
+    .filter(({ terms }) => terms.some((term) => term && normalized.includes(` ${term} `)))
+    .map(({ capability }) => capability.id_hint)
+    .sort();
+}
+
+function scenarioAction(title) {
+  const normalized = String(title || "").toLowerCase();
+  for (const [needle, action] of [
+    ["create", "create"],
+    ["add ", "create"],
+    ["new ", "create"],
+    ["list", "list"],
+    ["index", "list"],
+    ["get ", "get"],
+    ["view", "get"],
+    ["show", "get"],
+    ["update", "update"],
+    ["edit", "update"],
+    ["delete", "delete"],
+    ["remove", "delete"],
+    ["approve", "approve"],
+    ["reject", "reject"],
+    ["close", "close"],
+    ["complete", "complete"],
+    ["export", "export"],
+    ["download", "download"],
+    ["revision", "request_revision"]
+  ]) {
+    if (normalized.includes(needle)) return action;
+  }
+  return null;
+}
+
+function refineScenarioCapabilities(title, capabilityIds) {
+  const action = scenarioAction(title);
+  if (!action) {
+    return capabilityIds;
+  }
+  const matching = capabilityIds.filter((id) => id.startsWith(`cap_${action}_`));
+  return matching.length > 0 ? matching : capabilityIds;
+}
+
+export const genericVerificationExtractor = {
+  id: "verification.generic",
+  track: "verification",
+  detect(context) {
+    const { frameworks } = frameworkInfo(context);
+    const testFiles = findTestFiles(context);
+    if (frameworks.length === 0 && testFiles.length === 0) {
+      return { score: 0, reasons: [] };
+    }
+    return {
+      score: Math.min(95, 40 + frameworks.length * 10 + Math.min(testFiles.length, 8) * 4),
+      reasons: [
+        frameworks.length > 0 ? `detected frameworks: ${frameworks.join(", ")}` : null,
+        testFiles.length > 0 ? `detected ${testFiles.length} test file(s)` : null
+      ].filter(Boolean)
+    };
+  },
+  extract(context) {
+    const { frameworks, scripts } = frameworkInfo(context);
+    const files = findTestFiles(context);
+    const apiImport = context.priorResults.api || { candidates: { capabilities: [] } };
+    const matchers = capabilityMatchers(apiImport.candidates);
+    const findings = [];
+    const candidates = {
+      verifications: [],
+      scenarios: [],
+      frameworks,
+      scripts
+    };
+
+    for (const filePath of files) {
+      const source = readTextIfExists(filePath) || "";
+      const relativePath = normalizeImportRelativePath(context.paths, filePath);
+      const framework = inferFramework(filePath, frameworks);
+      const method = inferMethod(filePath, framework);
+      const titles = extractScenarioTitles(source, filePath);
+      const fileLabel = titleCase(pathStem(filePath));
+      const relatedCapabilities = inferRelatedCapabilities(`${relativePath}\n${source}`, matchers);
+      const verificationId = `verification_${idHintify(`${framework}_${relativePath}`)}`;
+      const scenarioIds = [];
+
+      for (const [index, title] of (titles.length > 0 ? titles : [fileLabel]).entries()) {
+        const scenarioId = `verification_scenario_${idHintify(`${framework}_${relativePath}_${title}`) || `${verificationId}_${index + 1}`}`;
+        const scenarioCapabilities = refineScenarioCapabilities(title, relatedCapabilities);
+        scenarioIds.push(scenarioId);
+        candidates.scenarios.push(makeCandidateRecord({
+          kind: "verification_scenario",
+          idHint: scenarioId,
+          label: title,
+          confidence: scenarioCapabilities.length > 0 ? "medium" : "low",
+          sourceKind: "test_suite",
+          provenance: relativePath,
+          track: "verification",
+          framework,
+          method,
+          file_path: relativePath,
+          verification_id: verificationId,
+          related_capabilities: scenarioCapabilities
+        }));
+      }
+
+      candidates.verifications.push(makeCandidateRecord({
+        kind: "verification",
+        idHint: verificationId,
+        label: fileLabel,
+        confidence: relatedCapabilities.length > 0 ? "medium" : "low",
+        sourceKind: "test_suite",
+        provenance: relativePath,
+        track: "verification",
+        framework,
+        method,
+        file_path: relativePath,
+        scenario_ids: scenarioIds,
+        related_capabilities: relatedCapabilities,
+        runner_scripts: scripts
+          .filter((script) => /(test|playwright|vitest|jest|cypress|pytest|rspec)/i.test(script.name) || /(playwright|vitest|jest|cypress|pytest|rspec)/i.test(script.command))
+          .map((script) => script.name)
+      }));
+    }
+
+    candidates.verifications = dedupeCandidateRecords(candidates.verifications, (record) => record.id_hint);
+    candidates.scenarios = dedupeCandidateRecords(candidates.scenarios, (record) => record.id_hint);
+
+    findings.push({
+      kind: "verification_import",
+      framework_count: frameworks.length,
+      test_file_count: files.length,
+      verification_count: candidates.verifications.length,
+      scenario_count: candidates.scenarios.length
+    });
+
+    return { findings, candidates };
+  }
+};
+
+function pathStem(filePath) {
+  const base = String(filePath || "").replaceAll("\\", "/").split("/").pop() || "verification";
+  return base
+    .replace(/\.(test|spec)\.[^.]+$/i, "")
+    .replace(/\.[^.]+$/i, "")
+    .replace(/[_-]+/g, " ");
+}

package/src/import/extractors/workflows/generic.js

@@ -0,0 +1,137 @@
+import { dedupeCandidateRecords, idHintify, inferCapabilityEntityId, makeCandidateRecord, titleCase } from "../../core/shared.js";
+
+function findEntityStatusFields(entity, enumCandidatesById) {
+  return (entity?.fields || []).filter((field) =>
+    ["status", "state"].includes(field.name) && enumCandidatesById.has(idHintify(field.field_type))
+  );
+}
+
+function targetStateForCapability(capability, knownStates) {
+  if (capability.target_state) {
+    const explicitState = idHintify(capability.target_state);
+    if (knownStates.length === 0 || knownStates.includes(explicitState)) return explicitState;
+  }
+  const id = capability.id_hint || "";
+  const method = String(capability.endpoint?.method || "").toUpperCase();
+  for (const [needle, state] of [
+    ["sign_in", "authenticated"],
+    ["login", "authenticated"],
+    ["authenticate", "authenticated"],
+    ["register", "registered"],
+    ["approve", "approved"],
+    ["reject", "rejected"],
+    ["revision", "needs_revision"],
+    ["request_revision", "needs_revision"],
+    ["submit", "submitted"],
+    ["close", "closed"],
+    ["complete", "completed"],
+    ["archive", "archived"],
+    ["delete", "deleted"],
+    [method === "POST" && id.startsWith("cap_create_") ? "create" : "", knownStates[0] || "created"]
+  ].filter(([needle]) => needle)) {
+    if (id.includes(needle)) {
+      const canonicalState = idHintify(state);
+      if (knownStates.length === 0 || knownStates.includes(canonicalState)) return canonicalState;
+    }
+  }
+  return null;
+}
+
+export const genericWorkflowExtractor = {
+  id: "workflows.generic",
+  track: "workflows",
+  detect() {
+    return { score: 50, reasons: ["Workflow inference runs over imported DB/API evidence"] };
+  },
+  extract(context) {
+    const dbImport = context.priorResults.db || { findings: [], candidates: { entities: [], enums: [] } };
+    const apiImport = context.priorResults.api || { findings: [], candidates: { capabilities: [] } };
+    const docScan = context.scanDocsSummary ? context.scanDocsSummary() : { candidate_docs: [] };
+    const findings = [];
+    const candidates = { workflows: [], workflow_states: [], workflow_transitions: [] };
+    const enumCandidatesById = new Map((dbImport.candidates.enums || []).map((entry) => [entry.id_hint, entry]));
+    const entityCandidatesById = new Map((dbImport.candidates.entities || []).map((entry) => [entry.id_hint, entry]));
+    const workflowDocs = (docScan.candidate_docs || []).filter((doc) => doc.kind === "workflow");
+    const workflows = new Map();
+
+    for (const capability of apiImport.candidates.capabilities || []) {
+      const entityId = inferCapabilityEntityId(capability);
+      const workflowId = `workflow_${entityId.replace(/^entity_/, "")}`;
+      const capabilityActors =
+        capability.auth_hint === "secured" ? ["user"] :
+        capability.auth_hint === "public" ? ["anonymous"] :
+        [];
+      if (!workflows.has(workflowId)) {
+        const entity = entityCandidatesById.get(entityId);
+        const statusFields = findEntityStatusFields(entity, enumCandidatesById);
+        const states = statusFields.flatMap((field) => enumCandidatesById.get(idHintify(field.field_type))?.values || []).map(idHintify);
+        workflows.set(workflowId, {
+          workflow: makeCandidateRecord({
+            kind: "workflow",
+            idHint: workflowId,
+            label: `${titleCase(entityId.replace(/^entity_/, ""))} Workflow`,
+            confidence: "medium",
+            sourceKind: "generated_artifact",
+            provenance: capability.provenance || [],
+            track: "workflows",
+            entity_id: entityId,
+            actor_hints: capabilityActors,
+            related_capabilities: []
+          }),
+          states: states.map((state) => makeCandidateRecord({
+            kind: "workflow_state",
+            idHint: `${workflowId}_${state}`,
+            label: titleCase(state),
+            confidence: "medium",
+            sourceKind: "schema",
+            provenance: entity?.provenance || capability.provenance || [],
+            track: "workflows",
+            workflow_id: workflowId,
+            entity_id: entityId,
+            state_id: state
+          })),
+          transitions: []
+        });
+      }
+      const workflow = workflows.get(workflowId);
+      workflow.workflow.related_capabilities.push(capability.id_hint);
+      workflow.workflow.actor_hints = [...new Set([...(workflow.workflow.actor_hints || []), ...capabilityActors])].sort();
+      const knownStates = workflow.states.map((entry) => entry.state_id);
+      const targetState = targetStateForCapability(capability, knownStates);
+      if (targetState) {
+        workflow.transitions.push(makeCandidateRecord({
+          kind: "workflow_transition",
+          idHint: `${workflowId}_${idHintify(capability.id_hint)}`,
+          label: titleCase(capability.id_hint.replace(/^cap_/, "")),
+          confidence: "low",
+          sourceKind: capability.source_kind || "generated_artifact",
+          provenance: capability.provenance || [],
+          track: "workflows",
+          workflow_id: workflowId,
+          entity_id: entityId,
+          capability_id: capability.id_hint,
+          actor_hints: capabilityActors,
+          to_state: targetState
+        }));
+      }
+    }
+
+    for (const workflow of workflows.values()) {
+      workflow.workflow.related_capabilities = [...new Set(workflow.workflow.related_capabilities)].sort();
+      candidates.workflows.push(workflow.workflow);
+      candidates.workflow_states.push(...workflow.states);
+      candidates.workflow_transitions.push(...workflow.transitions);
+    }
+
+    findings.push({
+      kind: "workflow_inference",
+      workflow_count: candidates.workflows.length,
+      workflow_doc_signals: workflowDocs.map((doc) => doc.id)
+    });
+
+    candidates.workflows = dedupeCandidateRecords(candidates.workflows, (record) => record.id_hint);
+    candidates.workflow_states = dedupeCandidateRecords(candidates.workflow_states, (record) => record.id_hint);
+    candidates.workflow_transitions = dedupeCandidateRecords(candidates.workflow_transitions, (record) => record.id_hint);
+    return { findings, candidates };
+  }
+};

package/src/import/index.js

@@ -0,0 +1,7 @@
+import { runImportApp, parseImportTracks } from "./core/runner.js";
+import { createImportContext, normalizeWorkspacePaths } from "./core/context.js";
+
+export { createImportContext, normalizeWorkspacePaths, parseImportTracks };
+export function runImportAppWorkflow(inputPath, options = {}) {
+  return runImportApp(inputPath, options);
+}

package/src/import/provenance.js

@@ -0,0 +1,158 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { listFilesRecursive, relativeTo } from "./core/shared.js";
+
+export const TOPOGRAM_IMPORT_FILE = ".topogram-import.json";
+
+function fileHash(filePath) {
+  const bytes = fs.readFileSync(filePath);
+  return {
+    sha256: crypto.createHash("sha256").update(bytes).digest("hex"),
+    size: bytes.length
+  };
+}
+
+function isSameOrInside(parent, child) {
+  const relative = path.relative(path.resolve(parent), path.resolve(child));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function normalizeExcludeRoots(sourceRoot, excludeRoots = []) {
+  return excludeRoots
+    .filter(Boolean)
+    .map((item) => path.resolve(item))
+    .filter((item) => isSameOrInside(sourceRoot, item));
+}
+
+export function collectImportSourceFileRecords(sourceRoot, options = {}) {
+  const resolvedSourceRoot = path.resolve(sourceRoot);
+  const excludeRoots = normalizeExcludeRoots(resolvedSourceRoot, options.excludeRoots || []);
+  return listFilesRecursive(resolvedSourceRoot, (filePath) => {
+    return !excludeRoots.some((excludeRoot) => isSameOrInside(excludeRoot, filePath));
+  }).map((filePath) => ({
+    path: relativeTo(resolvedSourceRoot, filePath),
+    ...fileHash(filePath)
+  }));
+}
+
+export function writeTopogramImportRecord(projectRoot, input) {
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const timestamp = input.timestamp || new Date().toISOString();
+  const record = {
+    version: "0.1",
+    kind: "brownfield-import",
+    importedAt: input.importedAt || timestamp,
+    ...(input.refreshedAt ? { refreshedAt: input.refreshedAt } : {}),
+    source: {
+      path: path.resolve(input.sourceRoot),
+      hashAlgorithm: "sha256",
+      ignoredRoots: (input.ignoredRoots || []).map((item) => path.resolve(item))
+    },
+    import: {
+      tracks: input.tracks || [],
+      findingsCount: input.findingsCount || 0,
+      candidateCounts: input.candidateCounts || {}
+    },
+    ownership: {
+      importedArtifacts: "project-owned",
+      note: "Topogram artifacts created by import are editable after import. Source hashes record the brownfield app evidence trusted at import time."
+    },
+    ...(input.refresh ? { refresh: input.refresh } : {}),
+    files: input.files || []
+  };
+  const importPath = path.join(resolvedProjectRoot, TOPOGRAM_IMPORT_FILE);
+  fs.writeFileSync(importPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  return { path: importPath, record };
+}
+
+export function buildTopogramImportStatus(projectRoot) {
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const importPath = path.join(resolvedProjectRoot, TOPOGRAM_IMPORT_FILE);
+  if (!fs.existsSync(importPath)) {
+    return {
+      ok: false,
+      exists: false,
+      path: importPath,
+      status: "missing",
+      source: null,
+      content: { changed: [], added: [], removed: [] },
+      diagnostics: [{
+        code: "topogram_import_missing",
+        severity: "error",
+        message: `${TOPOGRAM_IMPORT_FILE} was not found. This workspace does not have brownfield import provenance.`,
+        path: importPath,
+        suggestedFix: "Run `topogram import <app-path> --out <target>` to create an imported Topogram workspace."
+      }],
+      errors: [`${TOPOGRAM_IMPORT_FILE} was not found.`]
+    };
+  }
+
+  const source = JSON.parse(fs.readFileSync(importPath, "utf8"));
+  const sourceRoot = path.resolve(source.source?.path || "");
+  if (!sourceRoot || !fs.existsSync(sourceRoot) || !fs.statSync(sourceRoot).isDirectory()) {
+    const message = `Imported source path was not found: ${source.source?.path || "unknown"}`;
+    return {
+      ok: false,
+      exists: true,
+      path: importPath,
+      status: "missing-source",
+      source,
+      content: { changed: [], added: [], removed: [] },
+      diagnostics: [{
+        code: "topogram_import_source_missing",
+        severity: "error",
+        message,
+        path: source.source?.path || null,
+        suggestedFix: "Restore the imported source path or rerun import from the current brownfield app location."
+      }],
+      errors: [message]
+    };
+  }
+
+  const trustedFiles = Array.isArray(source.files) ? source.files : [];
+  const trustedByPath = new Map(trustedFiles.map((file) => [String(file.path), file]));
+  const currentFiles = collectImportSourceFileRecords(sourceRoot, {
+    excludeRoots: source.source?.ignoredRoots || [resolvedProjectRoot]
+  });
+  const currentByPath = new Map(currentFiles.map((file) => [file.path, file]));
+  const changed = [];
+  const added = [];
+  const removed = [];
+  for (const [filePath, current] of currentByPath) {
+    const trusted = trustedByPath.get(filePath);
+    if (!trusted) {
+      added.push(filePath);
+    } else if (trusted.sha256 !== current.sha256 || trusted.size !== current.size) {
+      changed.push(filePath);
+    }
+  }
+  for (const filePath of trustedByPath.keys()) {
+    if (!currentByPath.has(filePath)) {
+      removed.push(filePath);
+    }
+  }
+  const content = {
+    changed: changed.sort((a, b) => a.localeCompare(b)),
+    added: added.sort((a, b) => a.localeCompare(b)),
+    removed: removed.sort((a, b) => a.localeCompare(b))
+  };
+  const clean = content.changed.length === 0 && content.added.length === 0 && content.removed.length === 0;
+  return {
+    ok: clean,
+    exists: true,
+    path: importPath,
+    status: clean ? "clean" : "changed",
+    source,
+    content,
+    diagnostics: clean ? [] : [{
+      code: "topogram_import_source_changed",
+      severity: "error",
+      message: "Imported source files changed since they were trusted for this import.",
+      path: sourceRoot,
+      suggestedFix: "Review the source changes. If they should drive Topogram changes, rerun import or update the Topogram artifacts manually."
+    }],
+    errors: clean ? [] : ["Imported source files changed since import."]
+  };
+}