@topogram/cli 0.3.63 → 0.3.65

package/src/text-helpers.d.ts

@@ -0,0 +1,7 @@
+export const canonicalCandidateTerm: (value: unknown, options?: { technicalStopwords?: boolean }) => string;
+export const ensureTrailingNewline: (value: string) => string;
+export const extractRankedTerms: (markdown: string, options?: { technicalStopwords?: boolean }) => string[];
+export const idHintify: (value: unknown) => string;
+export const pluralizeCandidateTerm: (value: unknown) => string;
+export const slugify: (value: unknown) => string;
+export const titleCase: (value: unknown) => string;

package/src/text-helpers.js

@@ -0,0 +1,245 @@
+// @ts-check
+
+export const GENERIC_STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "into",
+  "your",
+  "their",
+  "have",
+  "will",
+  "when",
+  "where",
+  "what",
+  "which",
+  "then",
+  "than",
+  "been",
+  "being",
+  "does",
+  "each",
+  "just",
+  "also",
+  "through",
+  "about",
+  "because",
+  "after",
+  "before",
+  "under",
+  "over",
+  "still",
+  "they",
+  "them",
+  "there",
+  "these",
+  "those",
+  "more",
+  "most",
+  "some",
+  "only",
+  "very",
+  "same",
+  "much",
+  "many",
+  "other",
+  "used",
+  "using"
+]);
+
+export const TECHNICAL_STOPWORDS = new Set([
+  "readme",
+  "docs",
+  "topogram",
+  "generated",
+  "example",
+  "examples",
+  "app",
+  "apps",
+  "agreement",
+  "api",
+  "artifacts",
+  "bash",
+  "bundle",
+  "bundles",
+  "commands",
+  "compile",
+  "deployment",
+  "deploy",
+  "engine",
+  "environment",
+  "fixtures",
+  "files",
+  "fly",
+  "getting",
+  "implementation",
+  "include",
+  "layout",
+  "local",
+  "migrations",
+  "model",
+  "notes",
+  "npm",
+  "package",
+  "proof",
+  "react",
+  "recommended",
+  "report",
+  "reports",
+  "runnable",
+  "run",
+  "runtime",
+  "scripts",
+  "server",
+  "smoke",
+  "snapshot",
+  "sqlite",
+  "stack",
+  "stages",
+  "started",
+  "state",
+  "sveltekit",
+  "current",
+  "check",
+  "checks",
+  "env",
+  "usage",
+  "web",
+  "workspace"
+]);
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}\n`;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function slugify(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "untitled";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function idHintify(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "") || "untitled";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalCandidateTerm(value) {
+  const normalized = slugify(value);
+  if (normalized.endsWith("ies")) {
+    return `${normalized.slice(0, -3)}y`;
+  }
+  if (normalized === "status" || normalized === "stats") {
+    return normalized;
+  }
+  if (normalized.endsWith("s") && !normalized.endsWith("ss") && !normalized.endsWith("us") && !normalized.endsWith("is")) {
+    return normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function pluralizeCandidateTerm(value) {
+  const normalized = String(value || "");
+  if (!normalized) return "items";
+  const parts = normalized.split("_");
+  const last = parts.pop() || "item";
+  let plural = last;
+  if (last === "stats") {
+    plural = "stats";
+  } else if (last.endsWith("sis")) {
+    plural = `${last.slice(0, -2)}es`;
+  } else if (last.endsWith("y") && !/[aeiou]y$/.test(last)) {
+    plural = `${last.slice(0, -1)}ies`;
+  } else if (/(s|x|z|ch|sh)$/.test(last)) {
+    plural = `${last}es`;
+  } else {
+    plural = `${last}s`;
+  }
+  return [...parts, plural].join("_");
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function titleCase(value) {
+  return String(value || "")
+    .split(/[_\-\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+/**
+ * @param {{ technicalStopwords?: boolean }} [options]
+ * @returns {Set<string>}
+ */
+export function stopwordSet(options = {}) {
+  const includeTechnical = options.technicalStopwords !== false;
+  return new Set([
+    ...GENERIC_STOPWORDS,
+    ...(includeTechnical ? TECHNICAL_STOPWORDS : [])
+  ]);
+}
+
+/**
+ * @param {string} markdown
+ * @param {{ technicalStopwords?: boolean }} [options]
+ * @returns {string[]}
+ */
+export function extractRankedTerms(markdown, options = {}) {
+  const stopwords = stopwordSet(options);
+  const normalized = markdown
+    .replace(/\[[^\]]+\]\([^)]+\)/g, " ")
+    .replace(/\/Users\/[^\s)]+/g, " ")
+    .replace(/https?:\/\/[^\s)]+/g, " ")
+    .replace(/`([^`]+)`/g, " $1 ")
+    .replace(/[_/]/g, " ");
+  const frequency = new Map();
+  const headings = normalized.match(/^#+\s+(.+)$/gm) || [];
+  for (const heading of headings) {
+    for (const word of heading.toLowerCase().match(/\b[a-z][a-z0-9-]{2,}\b/g) || []) {
+      if (stopwords.has(word)) {
+        continue;
+      }
+      frequency.set(word, (frequency.get(word) || 0) + 3);
+    }
+  }
+  for (const word of normalized.toLowerCase().match(/\b[a-z][a-z0-9-]{2,}\b/g) || []) {
+    if (stopwords.has(word)) {
+      continue;
+    }
+    frequency.set(word, (frequency.get(word) || 0) + 1);
+  }
+  return [...frequency.entries()]
+    .sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0]))
+    .map(([term]) => term);
+}

package/src/topogram-config.js

@@ -0,0 +1,306 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const TOPOGRAM_CONFIG_FILE = "topogram.config.json";
+
+export const DEFAULT_FIRST_PARTY_GENERATOR_REPOS = [
+  "topogram-generator-express-api",
+  "topogram-generator-hono-api",
+  "topogram-generator-postgres-db",
+  "topogram-generator-react-web",
+  "topogram-generator-sqlite-db",
+  "topogram-generator-sveltekit-web",
+  "topogram-generator-swiftui-native",
+  "topogram-generator-vanilla-web"
+];
+
+export const DEFAULT_RELEASE_CONSUMER_REPOS = [
+  ...DEFAULT_FIRST_PARTY_GENERATOR_REPOS,
+  "topogram-starters",
+  "topogram-template-todo",
+  "topogram-demo-todo",
+  "topogram-hello",
+  "topograms"
+];
+
+export const DEFAULT_RELEASE_CONSUMER_WORKFLOWS = {
+  "topogram-generator-express-api": "Generator Verification",
+  "topogram-generator-hono-api": "Generator Verification",
+  "topogram-generator-postgres-db": "Generator Verification",
+  "topogram-generator-react-web": "Generator Verification",
+  "topogram-generator-sqlite-db": "Generator Verification",
+  "topogram-generator-sveltekit-web": "Generator Verification",
+  "topogram-generator-swiftui-native": "Generator Verification",
+  "topogram-generator-vanilla-web": "Generator Verification",
+  "topogram-starters": "Starter Verification",
+  "topogram-template-todo": "Template Verification",
+  "topogram-demo-todo": "Demo Verification",
+  "topogram-hello": "Topogram Package Verification",
+  "topograms": "Catalog Verification"
+};
+
+export const DEFAULT_RELEASE_CONSUMER_WORKFLOW_JOBS = {
+  topograms: [
+    "Validate catalog",
+    "Smoke native starter",
+    "Smoke starter alias (hello-web)",
+    "Smoke starter alias (hello-api)",
+    "Smoke starter alias (hello-db)",
+    "Smoke starter alias (web-api)",
+    "Smoke starter alias (web-api-db)"
+  ]
+};
+
+export const DEFAULT_TOPOGRAM_CONFIG = {
+  github: {
+    owner: "attebury",
+    repo: "topogram"
+  },
+  catalog: {
+    owner: "attebury",
+    repo: "topograms",
+    ref: "main",
+    path: "topograms.catalog.json",
+    source: null
+  },
+  release: {
+    consumers: DEFAULT_RELEASE_CONSUMER_REPOS,
+    workflows: DEFAULT_RELEASE_CONSUMER_WORKFLOWS,
+    workflowJobs: DEFAULT_RELEASE_CONSUMER_WORKFLOW_JOBS
+  }
+};
+
+export const DEFAULT_CATALOG_SOURCE = `https://raw.githubusercontent.com/${DEFAULT_TOPOGRAM_CONFIG.catalog.owner}/${DEFAULT_TOPOGRAM_CONFIG.catalog.repo}/${DEFAULT_TOPOGRAM_CONFIG.catalog.ref}/${DEFAULT_TOPOGRAM_CONFIG.catalog.path}`;
+
+/**
+ * @typedef {Object} TopogramRuntimeConfig
+ * @property {{ owner: string, repo: string }} github
+ * @property {{ owner: string, repo: string, ref: string, path: string, source: string|null }} catalog
+ * @property {{ consumers: string[], workflows: Record<string, string>, workflowJobs: Record<string, string[]> }} release
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+export function findTopogramConfigFile(cwd = process.cwd()) {
+  if (process.env.TOPOGRAM_CONFIG_PATH) {
+    return path.resolve(process.env.TOPOGRAM_CONFIG_PATH);
+  }
+  let current = path.resolve(cwd);
+  while (true) {
+    const candidate = path.join(current, TOPOGRAM_CONFIG_FILE);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Record<string, any>}
+ */
+export function readTopogramConfigFile(cwd = process.cwd()) {
+  const filePath = findTopogramConfigFile(cwd);
+  if (!filePath) {
+    return {};
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * @param {string|null|undefined} value
+ * @returns {string[]|null}
+ */
+function parseListEnv(value) {
+  if (!value) {
+    return null;
+  }
+  return String(value)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {string|null|undefined} value
+ * @returns {Record<string, any>|null}
+ */
+function parseJsonEnv(value) {
+  if (!value) {
+    return null;
+  }
+  return JSON.parse(value);
+}
+
+/**
+ * @param {Record<string, any>} fileConfig
+ * @returns {Record<string, any>}
+ */
+function envConfig(fileConfig = {}) {
+  const consumers = parseListEnv(process.env.TOPOGRAM_RELEASE_CONSUMERS);
+  const workflows = parseJsonEnv(process.env.TOPOGRAM_RELEASE_WORKFLOWS || process.env.TOPOGRAM_RELEASE_CONSUMER_WORKFLOWS_JSON);
+  const workflowJobs = parseJsonEnv(process.env.TOPOGRAM_RELEASE_WORKFLOW_JOBS || process.env.TOPOGRAM_RELEASE_CONSUMER_WORKFLOW_JOBS_JSON);
+  return {
+    github: {
+      owner: process.env.TOPOGRAM_GITHUB_OWNER || fileConfig.github?.owner,
+      repo: process.env.TOPOGRAM_GITHUB_REPO || process.env.TOPOGRAM_REPO_NAME || fileConfig.github?.repo
+    },
+    catalog: {
+      owner: process.env.TOPOGRAM_CATALOG_OWNER || fileConfig.catalog?.owner,
+      repo: process.env.TOPOGRAM_CATALOG_REPO || fileConfig.catalog?.repo,
+      ref: process.env.TOPOGRAM_CATALOG_REF || fileConfig.catalog?.ref,
+      path: process.env.TOPOGRAM_CATALOG_PATH || fileConfig.catalog?.path,
+      source: fileConfig.catalog?.source
+    },
+    release: {
+      consumers: consumers || fileConfig.release?.consumers,
+      workflows: workflows || fileConfig.release?.workflows,
+      workflowJobs: workflowJobs || fileConfig.release?.workflowJobs
+    }
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @param {string[]} fallback
+ * @returns {string[]}
+ */
+function normalizeStringList(value, fallback) {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+  const items = value.map((item) => String(item || "").trim()).filter(Boolean);
+  return [...new Set(items)];
+}
+
+/**
+ * @param {unknown} value
+ * @param {Record<string, string>} fallback
+ * @returns {Record<string, string>}
+ */
+function normalizeStringMap(value, fallback) {
+  const output = { ...fallback };
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return output;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    const name = String(key || "").trim();
+    const text = String(item || "").trim();
+    if (name && text) {
+      output[name] = text;
+    }
+  }
+  return output;
+}
+
+/**
+ * @param {unknown} value
+ * @param {Record<string, string[]>} fallback
+ * @returns {Record<string, string[]>}
+ */
+function normalizeStringListMap(value, fallback) {
+  const output = Object.fromEntries(Object.entries(fallback).map(([key, items]) => [key, [...items]]));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return output;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    const name = String(key || "").trim();
+    if (!name) {
+      continue;
+    }
+    output[name] = normalizeStringList(item, []);
+  }
+  return output;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {TopogramRuntimeConfig}
+ */
+export function topogramRuntimeConfig(cwd = process.cwd()) {
+  const fileConfig = readTopogramConfigFile(cwd);
+  const overrides = envConfig(fileConfig);
+  return {
+    github: {
+      owner: overrides.github.owner || DEFAULT_TOPOGRAM_CONFIG.github.owner,
+      repo: overrides.github.repo || DEFAULT_TOPOGRAM_CONFIG.github.repo
+    },
+    catalog: {
+      owner: overrides.catalog.owner || DEFAULT_TOPOGRAM_CONFIG.catalog.owner,
+      repo: overrides.catalog.repo || DEFAULT_TOPOGRAM_CONFIG.catalog.repo,
+      ref: overrides.catalog.ref || DEFAULT_TOPOGRAM_CONFIG.catalog.ref,
+      path: overrides.catalog.path || DEFAULT_TOPOGRAM_CONFIG.catalog.path,
+      source: overrides.catalog.source || DEFAULT_TOPOGRAM_CONFIG.catalog.source
+    },
+    release: {
+      consumers: normalizeStringList(overrides.release.consumers, DEFAULT_TOPOGRAM_CONFIG.release.consumers),
+      workflows: normalizeStringMap(overrides.release.workflows, DEFAULT_TOPOGRAM_CONFIG.release.workflows),
+      workflowJobs: normalizeStringListMap(overrides.release.workflowJobs, DEFAULT_TOPOGRAM_CONFIG.release.workflowJobs)
+    }
+  };
+}
+
+/**
+ * @param {TopogramRuntimeConfig} [config]
+ * @returns {string}
+ */
+export function defaultCatalogSource(config = topogramRuntimeConfig()) {
+  if (config.catalog.source) {
+    return config.catalog.source;
+  }
+  return `https://raw.githubusercontent.com/${config.catalog.owner}/${config.catalog.repo}/${config.catalog.ref}/${config.catalog.path}`;
+}
+
+/**
+ * @param {string|null|undefined} repo
+ * @param {string} [cwd]
+ * @param {string|null|undefined} owner
+ * @returns {string}
+ */
+export function githubRepoSlug(repo, cwd = process.cwd(), owner = null) {
+  const config = topogramRuntimeConfig(cwd);
+  return `${owner || config.github.owner}/${repo || config.github.repo}`;
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function catalogRepoSlug(cwd = process.cwd()) {
+  const config = topogramRuntimeConfig(cwd);
+  return githubRepoSlug(config.catalog.repo, cwd, config.catalog.owner);
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function releaseConsumerRepos(cwd = process.cwd()) {
+  return [...topogramRuntimeConfig(cwd).release.consumers];
+}
+
+/**
+ * @param {string} name
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function releaseConsumerWorkflowName(name, cwd = process.cwd()) {
+  return topogramRuntimeConfig(cwd).release.workflows[name] || null;
+}
+
+/**
+ * @param {string} name
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function releaseConsumerWorkflowJobs(name, cwd = process.cwd()) {
+  return [...(topogramRuntimeConfig(cwd).release.workflowJobs[name] || [])];
+}

package/src/topogram-types.d.ts

@@ -0,0 +1,69 @@
+export interface TopogramLocation {
+  file?: string;
+  start?: {
+    line?: number;
+    column?: number;
+    offset?: number;
+  };
+  end?: {
+    line?: number;
+    column?: number;
+    offset?: number;
+  };
+}
+
+export interface TopogramToken {
+  type: string;
+  value: any;
+  items: TopogramToken[];
+  entries: TopogramBlockEntry[];
+  loc: TopogramLocation;
+  [key: string]: any;
+}
+
+export interface TopogramBlockEntry {
+  items: TopogramToken[];
+  loc: TopogramLocation;
+  [key: string]: any;
+}
+
+export interface TopogramField {
+  key: string;
+  value: TopogramToken;
+  loc: TopogramLocation;
+  [key: string]: any;
+}
+
+export interface TopogramStatement {
+  id: string;
+  kind: string;
+  fields: TopogramField[];
+  loc: TopogramLocation;
+  [key: string]: any;
+}
+
+export interface ValidationError {
+  message: string;
+  loc?: TopogramLocation | null;
+}
+
+export type ValidationErrors = ValidationError[];
+
+export type TopogramFieldMap = Map<string, TopogramField[]>;
+
+export type TopogramRegistry = Map<string, TopogramStatement>;
+
+export type ResolverBacklinkIndex = Record<string, Map<string, string[]>>;
+
+declare global {
+  type TopogramLocation = import("./topogram-types.js").TopogramLocation;
+  type TopogramToken = import("./topogram-types.js").TopogramToken;
+  type TopogramBlockEntry = import("./topogram-types.js").TopogramBlockEntry;
+  type TopogramField = import("./topogram-types.js").TopogramField;
+  type TopogramStatement = import("./topogram-types.js").TopogramStatement;
+  type ValidationError = import("./topogram-types.js").ValidationError;
+  type ValidationErrors = import("./topogram-types.js").ValidationErrors;
+  type TopogramFieldMap = import("./topogram-types.js").TopogramFieldMap;
+  type TopogramRegistry = import("./topogram-types.js").TopogramRegistry;
+  type ResolverBacklinkIndex = import("./topogram-types.js").ResolverBacklinkIndex;
+}