@topogram/cli 0.3.84 → 0.3.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.84",
+  "version": "0.3.85",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/extractor/check.js

@@ -5,6 +5,7 @@ import {
   loadExtractorPackageAdapterForSpec,
   validateExtractorAdapter
 } from "./packages.js";
+import { validateExtractorResult } from "./output.js";
 
 /**
  * @typedef {import("./registry.js").ExtractorManifest} ExtractorManifest
@@ -25,39 +26,6 @@ import {
  * @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]
@@ -126,9 +94,9 @@ export function checkExtractorPack(sourceSpec, options = {}) {
         continue;
       }
       const result = extractor.extract(context) || { findings: [], candidates: {} };
-      const validation = validateExtractResult(result);
+      const validation = validateExtractorResult(result, { track: extractor.track, strictCandidates: true });
       if (!validation.ok || !validation.smoke) {
-        payload.errors.push(`Extractor '${extractor.id}' ${validation.message}.`);
+        payload.errors.push(...validation.errors.map((message) => `Extractor '${extractor.id}' ${message}.`));
         continue;
       }
       totalFindings += validation.smoke.findings;
@@ -152,4 +120,3 @@ export function checkExtractorPack(sourceSpec, options = {}) {
   payload.ok = payload.errors.length === 0;
   return payload;
 }
-

package/src/extractor/output.js

@@ -0,0 +1,220 @@
+// @ts-check
+
+/**
+ * @typedef {Object} ExtractorResultValidationOptions
+ * @property {string} [track]
+ * @property {boolean} [strictCandidates]
+ */
+
+/**
+ * @typedef {Object} ExtractorResultValidation
+ * @property {boolean} ok
+ * @property {string[]} errors
+ * @property {{ findings: number, candidateKeys: number, diagnostics: number }|null} smoke
+ */
+
+/** @type {Record<string, Set<string>>} */
+const TRACK_CANDIDATE_BUCKETS = {
+  db: new Set(["entities", "enums", "relations", "indexes", "maintained_seams"]),
+  api: new Set(["capabilities", "routes", "stacks"]),
+  ui: new Set(["screens", "routes", "actions", "flows", "widgets", "shapes", "stacks"]),
+  cli: new Set(["commands", "capabilities", "surfaces"]),
+  workflows: new Set(["workflows", "workflow_states", "workflow_transitions"]),
+  verification: new Set(["verifications", "scenarios", "frameworks", "scripts"])
+};
+
+const DISALLOWED_BUCKETS = new Set([
+  "adoption",
+  "adoption_plan",
+  "adoptionPlan",
+  "canonical",
+  "canonical_files",
+  "canonicalFiles",
+  "files",
+  "patches",
+  "project_config",
+  "projectConfig",
+  "topo",
+  "topogram",
+  "topogram_project",
+  "topogramProject",
+  "writeFiles",
+  "writes",
+  "writtenFiles"
+]);
+
+const DISALLOWED_RECORD_KEYS = new Set([
+  "adoption",
+  "adoptionPlan",
+  "canonical",
+  "canonicalFiles",
+  "files",
+  "patches",
+  "receipt",
+  "topo",
+  "topogram",
+  "write",
+  "writeFiles",
+  "writes",
+  "writtenFiles"
+]);
+
+/**
+ * Keys that carry local source/package file references. Deliberately excludes
+ * command/route `path` and config target dotted `path` values.
+ */
+const PATH_KEYS = new Set([
+  "configFile",
+  "configPath",
+  "file",
+  "filePath",
+  "migrationPath",
+  "migrationsPath",
+  "schemaPath",
+  "snapshotPath",
+  "sourceFile",
+  "sourcePath",
+  "source_path",
+  "targetFile",
+  "targetPath"
+]);
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {string} candidatePath
+ * @returns {boolean}
+ */
+function isUnsafeRelativePath(candidatePath) {
+  return candidatePath.startsWith("/") || candidatePath === ".." || candidatePath.startsWith("../") || candidatePath.includes("/../");
+}
+
+/**
+ * @param {string} bucket
+ * @param {Record<string, unknown>} candidate
+ * @returns {string[]}
+ */
+function identityFieldsForBucket(bucket, candidate) {
+  if (bucket === "commands") return ["command_id", "id_hint"];
+  if (bucket === "routes") {
+    if (typeof candidate.method === "string" && typeof candidate.path === "string") {
+      return [];
+    }
+    return ["id_hint", "id"];
+  }
+  return ["id_hint", "id", "name"];
+}
+
+/**
+ * @param {string} bucket
+ * @param {Record<string, unknown>} candidate
+ * @param {string} pathLabel
+ * @returns {string[]}
+ */
+function validateCandidateIdentity(bucket, candidate, pathLabel) {
+  const fields = identityFieldsForBucket(bucket, candidate);
+  if (fields.length === 0) return [];
+  if (fields.some((field) => typeof candidate[field] === "string" && String(candidate[field]).trim().length > 0)) {
+    return [];
+  }
+  return [`${pathLabel} must include an identity field: ${fields.join(" or ")}`];
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} pathLabel
+ * @param {string[]} errors
+ * @returns {void}
+ */
+function validateNoUnsafeRecords(value, pathLabel, errors) {
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      validateNoUnsafeRecords(value[index], `${pathLabel}[${index}]`, errors);
+    }
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${pathLabel}.${key}`;
+    if (DISALLOWED_RECORD_KEYS.has(key)) {
+      errors.push(`${childPath} is not allowed in extractor candidate output; extractors emit review candidates, not adoption plans or files.`);
+      continue;
+    }
+    if (PATH_KEYS.has(key) && typeof child === "string" && isUnsafeRelativePath(child)) {
+      errors.push(`${childPath} must be a safe project-relative path.`);
+      continue;
+    }
+    validateNoUnsafeRecords(child, childPath, errors);
+  }
+}
+
+/**
+ * @param {unknown} result
+ * @param {ExtractorResultValidationOptions} [options]
+ * @returns {ExtractorResultValidation}
+ */
+export function validateExtractorResult(result, options = {}) {
+  const errors = [];
+  if (!isPlainObject(result)) {
+    return { ok: false, errors: ["extract(context) must return an object"], smoke: null };
+  }
+  if (result.findings != null && !Array.isArray(result.findings)) {
+    errors.push("extract(context) findings must be an array when present");
+  }
+  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
+    errors.push("extract(context) diagnostics must be an array when present");
+  }
+  if (!isPlainObject(result.candidates)) {
+    errors.push("extract(context) result must include a candidates object");
+    return { ok: false, errors, smoke: null };
+  }
+
+  const allowedBuckets = options.track ? TRACK_CANDIDATE_BUCKETS[options.track] : null;
+  const candidateKeys = Object.keys(result.candidates);
+  for (const [bucket, value] of Object.entries(result.candidates)) {
+    const bucketLabel = `extract(context) candidates.${bucket}`;
+    if (DISALLOWED_BUCKETS.has(bucket)) {
+      errors.push(`${bucketLabel} is not allowed; extractors must not return adoption plans, canonical files, patches, or topo writes.`);
+      continue;
+    }
+    if (options.strictCandidates && allowedBuckets && !allowedBuckets.has(bucket)) {
+      errors.push(`${bucketLabel} is not allowed for track '${options.track}'.`);
+      continue;
+    }
+    if (!Array.isArray(value)) {
+      errors.push(`${bucketLabel} must be an array`);
+      continue;
+    }
+    if (!options.strictCandidates) continue;
+    for (let index = 0; index < value.length; index += 1) {
+      const candidate = value[index];
+      const candidateLabel = `${bucketLabel}[${index}]`;
+      if (!isPlainObject(candidate)) {
+        errors.push(`${candidateLabel} must be an object.`);
+        continue;
+      }
+      errors.push(...validateCandidateIdentity(bucket, candidate, candidateLabel));
+      validateNoUnsafeRecords(candidate, candidateLabel, errors);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    smoke: errors.length === 0
+      ? {
+          findings: Array.isArray(result.findings) ? result.findings.length : 0,
+          candidateKeys: candidateKeys.length,
+          diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics.length : 0
+        }
+      : null
+  };
+}
+
+export { TRACK_CANDIDATE_BUCKETS };

package/src/extractor/scaffold.js

@@ -457,6 +457,11 @@ npm run check
 Replace the scaffold adapter in \`index.cjs\` with precise, read-only source evidence.
 Extractor packages must not mutate source files, write canonical \`topo/**\`, install
 packages, perform network access, or define adoption semantics.
+
+Candidate output is validated by track. Return only review candidate buckets for
+the declared track, give each candidate a stable identity, keep file evidence
+project-relative, and never return files, patches, adoption plans, or write
+instructions.
 `
   };
   for (const [relative, contents] of Object.entries(defaults.fixtureFiles)) {

package/src/import/core/runner/tracks.js

@@ -3,6 +3,7 @@
 import { getEnrichersForTrack, getExtractorsForTrack } from "../registry.js";
 import { normalizeCandidatesForTrack } from "./candidates.js";
 import { packageExtractorsForContext } from "../../../extractor/packages.js";
+import { validateExtractorResult } from "../../../extractor/output.js";
 
 /**
  * @param {any} context
@@ -140,25 +141,12 @@ function initialCandidatesForTrack(track) {
  */
 function assertExtractorResultShape(extractor, result) {
   const label = extractor?.id || "unknown";
-  if (!result || typeof result !== "object" || Array.isArray(result)) {
-    throw new Error(`Extractor '${label}' extract(context) must return an object.`);
-  }
-  if (result.findings != null && !Array.isArray(result.findings)) {
-    throw new Error(`Extractor '${label}' extract(context) findings must be an array when present.`);
-  }
-  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
-    throw new Error(`Extractor '${label}' extract(context) diagnostics must be an array when present.`);
-  }
-  if (result.candidates == null) {
-    result.candidates = {};
-  }
-  if (!result.candidates || typeof result.candidates !== "object" || Array.isArray(result.candidates)) {
-    throw new Error(`Extractor '${label}' extract(context) candidates must be an object.`);
-  }
-  for (const [key, value] of Object.entries(result.candidates)) {
-    if (!Array.isArray(value)) {
-      throw new Error(`Extractor '${label}' extract(context) candidates.${key} must be an array.`);
-    }
+  const validation = validateExtractorResult(result, {
+    track: extractor?.track,
+    strictCandidates: extractor?.source === "package"
+  });
+  if (!validation.ok) {
+    throw new Error(validation.errors.map((message) => `Extractor '${label}' ${message}.`).join("\n"));
   }
 }