@topogram/cli 0.3.79 → 0.3.81

package/src/cli/commands/import/help.js

@@ -4,7 +4,7 @@ import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { TOPOGRAM_IMPORT_ADOPTIONS_FILE } from "./paths.js";
 
 export function printExtractHelp() {
-  console.log("Usage: topogram extract <app-path> --out <target> [--from <track[,track]>] [--json]");
+  console.log("Usage: topogram extract <app-path> --out <target> [--from <track[,track]>] [--extractor <id-or-package-or-path>] [--json]");
   console.log("   or: topogram extract refresh [path] [--from <app-path>] [--dry-run] [--json]");
   console.log("   or: topogram extract diff [path] [--json]");
   console.log("   or: topogram extract check [path] [--json]");
@@ -26,6 +26,8 @@ export function printExtractHelp() {
   console.log("  topogram extract ./existing-app --out ./extracted-topogram");
   console.log("  topogram extract ./existing-app --out ./extracted-topogram --from db,api,ui");
   console.log("  topogram extract ./existing-cli --out ./extracted-topogram --from cli");
+  console.log("  topogram extract ./existing-cli --out ./extracted-topogram --from cli --extractor @topogram/extractor-node-cli");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram --extractor-policy ./topogram.extractor-policy.json");
   console.log("  topogram extract diff ./extracted-topogram");
   console.log("  topogram extract refresh ./extracted-topogram --from ./existing-app --dry-run");
   console.log("  topogram extract refresh ./extracted-topogram --from ./existing-app");

package/src/cli/commands/import/workspace.js

@@ -149,7 +149,7 @@ export function countFilesRecursive(rootPath) {
 /**
  * @param {string} sourcePath
  * @param {string} targetPath
- * @param {{ from?: string|null }} [options]
+ * @param {{ from?: string|null, extractorSpecs?: string[], extractorPolicyPath?: string|null, cwd?: string|null }} [options]
  * @returns {{ ok: boolean, sourcePath: string, targetPath: string, workspaceRoot: string, topogramRoot: string, projectConfigPath: string, provenancePath: string, tracks: string[], sourceFiles: number, rawCandidateFiles: number, reconcileFiles: number, writtenFiles: string[], candidateCounts: Record<string, number>, nextCommands: string[] }}
  */
 export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, options = {}) {
@@ -166,7 +166,12 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
   const topogramRoot = path.join(targetRoot, DEFAULT_TOPO_FOLDER_NAME);
   fs.mkdirSync(topogramRoot, { recursive: true });
   const sourceFiles = collectImportSourceFileRecords(sourceRoot, { excludeRoots: [targetRoot] });
-  const importResult = runWorkflow("import-app", sourceRoot, { from: options.from || null });
+  const importResult = runWorkflow("import-app", sourceRoot, {
+    from: options.from || null,
+    extractorSpecs: options.extractorSpecs || [],
+    extractorPolicyPath: options.extractorPolicyPath || null,
+    cwd: options.cwd || process.cwd()
+  });
   const rawCandidateFiles = writeRelativeFiles(topogramRoot, importResult.files || {});
 
   const projectConfigPath = path.join(targetRoot, "topogram.project.json");
@@ -182,6 +187,7 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
     tracks: importResult.summary.tracks || [],
     findingsCount: importResult.summary.findings_count || 0,
     candidateCounts,
+    extractorPackages: importResult.summary.package_extractors || [],
     files: sourceFiles
   });
   const writtenFiles = [

package/src/cli/commands/import-runner.js

@@ -25,7 +25,7 @@ import {
 } from "./import.js";
 
 /**
- * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, outPath?: string|null, fromValue?: string|null, reasonValue?: string|null, refreshAdopted?: boolean, dryRun?: boolean, write?: boolean, force?: boolean, json?: boolean }} context
+ * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, outPath?: string|null, fromValue?: string|null, extractorSpecs?: string[], extractorPolicyPath?: string|null, reasonValue?: string|null, refreshAdopted?: boolean, dryRun?: boolean, write?: boolean, force?: boolean, json?: boolean }} context
  * @returns {number}
  */
 export function runImportCommand(context) {
@@ -34,6 +34,8 @@ export function runImportCommand(context) {
     inputPath,
     outPath = null,
     fromValue = null,
+    extractorSpecs = [],
+    extractorPolicyPath = null,
     reasonValue = null,
     refreshAdopted = false,
     dryRun = false,
@@ -49,7 +51,7 @@ export function runImportCommand(context) {
       printExtractHelp();
       return 1;
     }
-    const payload = buildBrownfieldImportWorkspacePayload(inputPath || "", outPath, { from: fromValue });
+    const payload = buildBrownfieldImportWorkspacePayload(inputPath || "", outPath, { from: fromValue, extractorSpecs, extractorPolicyPath, cwd: process.cwd() });
     if (json) {
       console.log(stableStringify(payload));
     } else {

package/src/cli/dispatcher.js

@@ -8,6 +8,7 @@ import { runCheckCommand } from "./commands/check.js";
 import { runCopyCommand } from "./commands/copy.js";
 import { runEmitCommand } from "./commands/emit.js";
 import { runGenerateAppCommand } from "./commands/generate.js";
+import { runExtractorCommand } from "./commands/extractor.js";
 import { runGeneratorCommand } from "./commands/generator.js";
 import { runGeneratorPolicyCommand } from "./commands/generator-policy.js";
 import { runImportCommand } from "./commands/import-runner.js";
@@ -81,6 +82,8 @@ export async function runCliDispatch(context) {
     workflowName,
     workflowId,
     fromValue,
+    extractorSpecs,
+    extractorPolicyPath,
     adoptValue,
     reasonValue,
     modeId,
@@ -225,6 +228,15 @@ export async function runCliDispatch(context) {
     });
   }
 
+  if (commandArgs?.extractorCommand || commandArgs?.extractorPolicyCommand) {
+    return runExtractorCommand({
+      commandArgs,
+      inputPath,
+      json: emitJson,
+      cwd: process.cwd()
+    });
+  }
+
   if (commandArgs?.generatorPolicyCommand) {
     return runGeneratorPolicyCommand({ commandArgs, inputPath, json: emitJson });
   }
@@ -259,6 +271,8 @@ export async function runCliDispatch(context) {
       inputPath,
       outPath,
       fromValue,
+      extractorSpecs,
+      extractorPolicyPath,
       reasonValue,
       refreshAdopted,
       dryRun: args.includes("--dry-run"),

package/src/cli/help-dispatch.js

@@ -12,6 +12,9 @@ import {
 import {
   printDoctorHelp
 } from "./commands/doctor.js";
+import {
+  printExtractorHelp
+} from "./commands/extractor.js";
 import {
   printGeneratorHelp
 } from "./commands/generator.js";
@@ -86,6 +89,10 @@ export function printCommandHelp(command) {
     printGeneratorHelp();
     return true;
   }
+  if (command === "extractor") {
+    printExtractorHelp();
+    return true;
+  }
   if (command === "template") {
     printTemplateHelp();
     return true;
@@ -176,6 +183,10 @@ export function handleUnparsedCommandHelp(args) {
     printGeneratorHelp();
     return args[1] ? 1 : 0;
   }
+  if (args[0] === "extractor") {
+    printExtractorHelp();
+    return args[1] ? 1 : 0;
+  }
   if (args[0] === "template") {
     printTemplateHelp();
     return args[1] ? 1 : 0;

package/src/cli/help.js

@@ -38,7 +38,7 @@ export function printUsage(options = {}) {
   console.log("   or: topogram package update-cli <version|--latest> [--json]");
   console.log("   or: topogram copy <source> <target> [--version <version>] [--catalog <path-or-source>] [--json]");
   console.log("   or: topogram copy --list [--json] [--catalog <path-or-source>]");
-  console.log("   or: topogram extract <app-path> --out <target> [--from <track[,track]>] [--json]");
+  console.log("   or: topogram extract <app-path> --out <target> [--from <track[,track]>] [--extractor <id-or-package-or-path>] [--json]");
   console.log("   or: topogram extract refresh [path] [--from <app-path>] [--dry-run] [--json]");
   console.log("   or: topogram extract diff [path] [--json]");
   console.log("   or: topogram extract check [path] [--json]");
@@ -67,6 +67,14 @@ export function printUsage(options = {}) {
   console.log("   or: topogram generator policy check [path] [--json]");
   console.log("   or: topogram generator policy explain [path] [--json]");
   console.log("   or: topogram generator policy pin [package@version] [path] [--json]");
+  console.log("   or: topogram extractor list [--json]");
+  console.log("   or: topogram extractor show <id-or-package> [--json]");
+  console.log("   or: topogram extractor check <path-or-package> [--json]");
+  console.log("   or: topogram extractor policy init [path] [--json]");
+  console.log("   or: topogram extractor policy status [path] [--json]");
+  console.log("   or: topogram extractor policy check [path] [--json]");
+  console.log("   or: topogram extractor policy explain [path] [--json]");
+  console.log("   or: topogram extractor policy pin [package@version] [path] [--json]");
   console.log("   or: topogram init [path] [--with-sdlc] [--json]");
   console.log("");
   console.log("Common commands:");
@@ -98,6 +106,11 @@ export function printUsage(options = {}) {
   console.log("  topogram generator show @topogram/generator-react-web");
   console.log("  topogram generator check ./generator-package");
   console.log("  topogram generator policy check");
+  console.log("  topogram extractor list");
+  console.log("  topogram extractor show @topogram/extractor-prisma-db");
+  console.log("  topogram extractor check ./extractor-package");
+  console.log("  topogram extractor policy check");
+  console.log("  topogram extract ./express-api --out ./extracted-topogram --from api --extractor @topogram/extractor-express-api");
   console.log("  topogram generate");
   console.log("  topogram extract ./existing-app --out ./extracted-topogram");
   console.log("  topogram extract diff ./extracted-topogram");

package/src/cli/options.js

@@ -22,6 +22,21 @@ export function optionValueIfPresent(args, flag) {
   return value && !value.startsWith("-") ? value : null;
 }
 
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {string[]}
+ */
+export function optionValues(args, flag) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag && args[index + 1] && !args[index + 1].startsWith("-")) {
+      values.push(args[index + 1]);
+    }
+  }
+  return values;
+}
+
 /**
  * @param {string[]} args
  * @param {string} flag
@@ -51,6 +66,8 @@ export function parseCliOptions(args, commandArgs) {
     workflowName: commandArgs?.workflowName || (!generateTarget && workflowFlagValue ? workflowFlagValue : null),
     workflowId: generateTarget ? workflowFlagValue : null,
     fromValue: optionValue(args, "--from"),
+    extractorSpecs: optionValues(args, "--extractor"),
+    extractorPolicyPath: optionValueIfPresent(args, "--extractor-policy"),
     adoptValue: commandArgs?.adoptValue || optionValue(args, "--adopt"),
     reasonValue: optionValueIfPresent(args, "--reason"),
     modeId: optionValue(args, "--mode"),

package/src/extractor/check.js

@@ -0,0 +1,155 @@
+// @ts-check
+
+import {
+  createExtractorSmokeContext,
+  loadExtractorPackageAdapterForSpec,
+  validateExtractorAdapter
+} from "./packages.js";
+
+/**
+ * @typedef {import("./registry.js").ExtractorManifest} ExtractorManifest
+ */
+
+/**
+ * @typedef {Object} ExtractorCheckResult
+ * @property {boolean} ok
+ * @property {string} sourceSpec
+ * @property {"path"|"package"} source
+ * @property {string|null} packageName
+ * @property {string|null} packageRoot
+ * @property {string|null} manifestPath
+ * @property {ExtractorManifest|null} manifest
+ * @property {Array<{ name: string, ok: boolean, message: string }>} checks
+ * @property {string[]} errors
+ * @property {{ extractors: number, findings: number, candidateKeys: number, diagnostics: number }|null} smoke
+ * @property {boolean} executesPackageCode
+ */
+
+/**
+ * @param {any} result
+ * @returns {{ ok: boolean, message: string, smoke: { findings: number, candidateKeys: number, diagnostics: number }|null }}
+ */
+function validateExtractResult(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return { ok: false, message: "extract(context) must return an object", smoke: null };
+  }
+  if (result.findings != null && !Array.isArray(result.findings)) {
+    return { ok: false, message: "extract(context) findings must be an array when present", smoke: null };
+  }
+  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
+    return { ok: false, message: "extract(context) diagnostics must be an array when present", smoke: null };
+  }
+  if (!result.candidates || typeof result.candidates !== "object" || Array.isArray(result.candidates)) {
+    return { ok: false, message: "extract(context) result must include a candidates object", smoke: null };
+  }
+  for (const [key, value] of Object.entries(result.candidates)) {
+    if (!Array.isArray(value)) {
+      return { ok: false, message: `extract(context) candidates.${key} must be an array`, smoke: null };
+    }
+  }
+  return {
+    ok: true,
+    message: `extract(context) returned ${Object.keys(result.candidates).length} candidate bucket(s)`,
+    smoke: {
+      findings: Array.isArray(result.findings) ? result.findings.length : 0,
+      candidateKeys: Object.keys(result.candidates).length,
+      diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics.length : 0
+    }
+  };
+}
+
+/**
+ * @param {string} sourceSpec
+ * @param {{ cwd?: string }} [options]
+ * @returns {ExtractorCheckResult}
+ */
+export function checkExtractorPack(sourceSpec, options = {}) {
+  /** @type {ExtractorCheckResult} */
+  const payload = {
+    ok: false,
+    sourceSpec,
+    source: "package",
+    packageName: null,
+    packageRoot: null,
+    manifestPath: null,
+    manifest: null,
+    checks: [],
+    errors: [],
+    smoke: null,
+    executesPackageCode: true
+  };
+  if (!sourceSpec || sourceSpec.startsWith("-")) {
+    payload.errors.push("Usage: topogram extractor check <path-or-package>");
+    payload.checks.push({ name: "source", ok: false, message: payload.errors[0] });
+    return payload;
+  }
+
+  const loaded = loadExtractorPackageAdapterForSpec(sourceSpec, options);
+  payload.source = loaded.source;
+  payload.packageName = loaded.packageName;
+  payload.packageRoot = loaded.packageRoot;
+  payload.manifestPath = loaded.manifestPath;
+  payload.manifest = loaded.manifest;
+  if (!loaded.manifest) {
+    payload.errors.push(...loaded.errors);
+    payload.checks.push({ name: "manifest-load", ok: false, message: loaded.errors.join(" ") || "Could not load extractor manifest." });
+    return payload;
+  }
+  payload.checks.push({ name: "manifest-load", ok: true, message: loaded.manifestPath || sourceSpec });
+  if (!loaded.adapter || loaded.errors.length > 0) {
+    payload.errors.push(...loaded.errors);
+    payload.checks.push({ name: "adapter-load", ok: false, message: loaded.errors.join(" ") || "Could not load extractor adapter." });
+    return payload;
+  }
+  payload.checks.push({ name: "adapter-load", ok: true, message: "Adapter export loaded." });
+
+  const adapterValidation = validateExtractorAdapter(loaded.adapter, loaded.manifest);
+  payload.checks.push({
+    name: "adapter-shape",
+    ok: adapterValidation.errors.length === 0,
+    message: adapterValidation.errors.length === 0 ? "Adapter shape is valid." : adapterValidation.errors.join(" ")
+  });
+  if (adapterValidation.errors.length > 0) {
+    payload.errors.push(...adapterValidation.errors);
+    return payload;
+  }
+
+  const context = createExtractorSmokeContext();
+  let totalFindings = 0;
+  let totalCandidateKeys = 0;
+  let totalDiagnostics = 0;
+  for (const extractor of adapterValidation.extractors) {
+    try {
+      const detection = extractor.detect(context) || { score: 0, reasons: [] };
+      if (!detection || typeof detection !== "object" || typeof detection.score !== "number") {
+        payload.errors.push(`Extractor '${extractor.id}' detect(context) must return { score, reasons }.`);
+        continue;
+      }
+      const result = extractor.extract(context) || { findings: [], candidates: {} };
+      const validation = validateExtractResult(result);
+      if (!validation.ok || !validation.smoke) {
+        payload.errors.push(`Extractor '${extractor.id}' ${validation.message}.`);
+        continue;
+      }
+      totalFindings += validation.smoke.findings;
+      totalCandidateKeys += validation.smoke.candidateKeys;
+      totalDiagnostics += validation.smoke.diagnostics;
+    } catch (error) {
+      payload.errors.push(`Extractor '${extractor.id}' smoke failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  payload.checks.push({
+    name: "smoke-extract",
+    ok: payload.errors.length === 0,
+    message: payload.errors.length === 0 ? `Ran ${adapterValidation.extractors.length} extractor smoke check(s).` : payload.errors.join(" ")
+  });
+  payload.smoke = {
+    extractors: adapterValidation.extractors.length,
+    findings: totalFindings,
+    candidateKeys: totalCandidateKeys,
+    diagnostics: totalDiagnostics
+  };
+  payload.ok = payload.errors.length === 0;
+  return payload;
+}
+

package/src/extractor/first-party.js

@@ -0,0 +1,93 @@
+// @ts-check
+
+export const FIRST_PARTY_EXTRACTOR_PACKAGES = [
+  {
+    package: "@topogram/extractor-prisma-db",
+    id: "@topogram/extractor-prisma-db",
+    version: "1",
+    label: "Prisma DB",
+    tracks: ["db"],
+    stack: { orm: "prisma", domain: "database" },
+    capabilities: { schema: true, migrations: true, maintainedSeams: true },
+    candidateKinds: ["entity", "enum", "relation", "index", "maintained_db_migration_seam"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["db.prisma"],
+    useWhen: "Use for Prisma schema.prisma models plus Prisma migration evidence.",
+    extracts: ["entities", "enums", "relations", "indexes", "maintained DB seam proposals"],
+    exampleSource: "./prisma-app"
+  },
+  {
+    package: "@topogram/extractor-express-api",
+    id: "@topogram/extractor-express-api",
+    version: "1",
+    label: "Express API",
+    tracks: ["api"],
+    stack: { runtime: "node", framework: "express" },
+    capabilities: { routes: true, parameters: true, authHints: true },
+    candidateKinds: ["capability", "route", "stack"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["api.express"],
+    useWhen: "Use for Express route files, routers, params, middleware, and auth hints.",
+    extracts: ["API route candidates", "capability suggestions", "parameter evidence", "auth hints", "stack evidence"],
+    exampleSource: "./express-api"
+  },
+  {
+    package: "@topogram/extractor-drizzle-db",
+    id: "@topogram/extractor-drizzle-db",
+    version: "1",
+    label: "Drizzle DB",
+    tracks: ["db"],
+    stack: { orm: "drizzle", domain: "database" },
+    capabilities: { schema: true, migrations: true, maintainedSeams: true },
+    candidateKinds: ["entity", "enum", "relation", "index", "maintained_db_migration_seam"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["db.drizzle"],
+    useWhen: "Use for Drizzle config, schema modules, table definitions, and migration output.",
+    extracts: ["entities", "relations", "indexes", "maintained DB seam proposals", "schema/migration evidence"],
+    exampleSource: "./drizzle-app"
+  },
+  {
+    package: "@topogram/extractor-node-cli",
+    id: "@topogram/extractor-node-cli",
+    version: "1",
+    label: "Node CLI",
+    tracks: ["cli"],
+    stack: { runtime: "node", domain: "cli" },
+    capabilities: { commands: true, options: true, effects: true },
+    candidateKinds: ["command", "capability", "cli_surface"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["cli.node-package"],
+    useWhen: "Use for Node package CLIs with bin entries, scripts, command modules, and help text.",
+    extracts: ["command candidates", "options", "effects", "CLI surface projections", "capability suggestions"],
+    exampleSource: "./existing-cli"
+  },
+  {
+    package: "@topogram/extractor-react-router",
+    id: "@topogram/extractor-react-router",
+    version: "1",
+    label: "React Router UI",
+    tracks: ["ui"],
+    stack: { framework: "react-router", domain: "ui" },
+    capabilities: { routes: true, screens: true, flows: true, widgets: true },
+    candidateKinds: ["screen", "route", "action", "flow", "widget", "shape", "stack"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["ui.react-router"],
+    useWhen: "Use for React Router route trees, route modules, screen hints, and non-resource UI flows.",
+    extracts: ["screens", "routes", "flow candidates", "widget evidence", "stack evidence"],
+    exampleSource: "./react-router-app"
+  }
+];
+
+export const FIRST_PARTY_EXTRACTORS_BY_PACKAGE = new Map(FIRST_PARTY_EXTRACTOR_PACKAGES.map((item) => [item.package, item]));
+export const FIRST_PARTY_EXTRACTORS_BY_ID = new Map(FIRST_PARTY_EXTRACTOR_PACKAGES.map((item) => [item.id, item]));
+
+/**
+ * @param {string|null|undefined} value
+ * @returns {typeof FIRST_PARTY_EXTRACTOR_PACKAGES[number]|null}
+ */
+export function firstPartyExtractorInfo(value) {
+  if (!value) {
+    return null;
+  }
+  return FIRST_PARTY_EXTRACTORS_BY_PACKAGE.get(value) || FIRST_PARTY_EXTRACTORS_BY_ID.get(value) || null;
+}