| 1 | /** |
| 2 | * What a project is (an app, a library, a tool, docs or other) and where |
| 3 | * it runs (hosted on g1t.page, deploying itself to hosting of its own, or |
| 4 | * nowhere). A person can say either in its |
| 5 | * settings; left to detection, it is worked out here from what the project |
| 6 | * has: Deployments being on, packages its repository publishes, and the |
| 7 | * files at its root. The functions are pure so the rules can be tested on |
| 8 | * their own; the service reads the files and keeps the detection by commit. |
| 9 | */ |
| 10 | |
| 11 | import type { KindReason, ProjectEcosystem, ProjectKind, ProjectRuns, ProjectSetting } from "@g1t/contracts"; |
| 12 | |
| 13 | /** As contracts' PROJECT_KINDS; repeated so this module's tests run without the package. */ |
| 14 | const PROJECT_KINDS: readonly ProjectKind[] = ["app", "library", "tool", "docs", "other"]; |
| 15 | |
| 16 | /** The manifests whose contents detection reads, when they are at the root. */ |
| 17 | export const MANIFESTS = ["composer.json", "Cargo.toml", "go.mod", "pyproject.toml", "package.json"] as const; |
| 18 | /** At most this many root `.go` files are read to find `package main`. */ |
| 19 | export const GO_FILES_READ = 3; |
| 20 | |
| 21 | /** What detection is given: the project's root, and what was read from it. */ |
| 22 | export type RootFiles = { |
| 23 | /** Names at the project's root; directories end in `/`. */ |
| 24 | entries: string[]; |
| 25 | /** Contents of the manifests and root `.go` files read, by name. */ |
| 26 | text: Record<string, string>; |
| 27 | /** Names in `src/`, when the root has a Cargo.toml. */ |
| 28 | src?: string[]; |
| 29 | /** Names in `public/`, when the root has a composer.json. */ |
| 30 | public?: string[]; |
| 31 | }; |
| 32 | |
| 33 | /** What the files say: a kind with why, or null when nothing says either way. */ |
| 34 | export type Detection = { kind: ProjectKind | null; detail: string; ecosystem: ProjectEcosystem | null }; |
| 35 | |
| 36 | /** Root `.go` files detection reads, tests left out. */ |
| 37 | export function goFilesToRead(entries: string[]): string[] { |
| 38 | return entries.filter((name) => name.endsWith(".go") && !name.endsWith("_test.go")).slice(0, GO_FILES_READ); |
| 39 | } |
| 40 | |
| 41 | const has = (files: RootFiles, name: string) => files.entries.includes(name); |
| 42 | |
| 43 | /** Frameworks that make a package.json an app. Hosting a server alone does not: a start script does. */ |
| 44 | const JS_APP_FRAMEWORKS = ["next", "astro", "nuxt", "@remix-run/dev", "@remix-run/node", "@react-router/dev", "@sveltejs/kit", "gatsby", "@angular/core", "expo", "react-scripts"]; |
| 45 | /** Documentation generators' configs: a root with one is documentation. */ |
| 46 | const DOCS_CONFIGS = ["mkdocs.yml", "mkdocs.yaml", "book.toml", "docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs", "antora.yml"]; |
| 47 | /** Python frameworks that make a pyproject an app. */ |
| 48 | const PY_APP_FRAMEWORKS = ["django", "flask", "fastapi", "streamlit", "gradio", "starlette", "uvicorn"]; |
| 49 | |
| 50 | function composer(files: RootFiles, text: string): Detection { |
| 51 | const ecosystem = "composer"; |
| 52 | let json: { type?: unknown; autoload?: unknown }; |
| 53 | try { |
| 54 | json = JSON.parse(text); |
| 55 | } catch { |
| 56 | return { kind: null, detail: "composer.json could not be read.", ecosystem }; |
| 57 | } |
| 58 | const type = typeof json.type === "string" ? json.type : null; |
| 59 | if (type === "project") return { kind: "app", detail: 'composer.json says "type": "project".', ecosystem }; |
| 60 | if (type) return { kind: "library", detail: `composer.json says "type": "${type}".`, ecosystem }; |
| 61 | const servesIndex = files.public?.includes("index.php") || has(files, "index.php"); |
| 62 | if (json.autoload && !servesIndex) { |
| 63 | return { kind: "library", detail: "composer.json has autoload and no public/index.php.", ecosystem }; |
| 64 | } |
| 65 | if (servesIndex) return { kind: "app", detail: "It has a composer.json and an index.php to serve.", ecosystem }; |
| 66 | return { kind: null, detail: "composer.json has no type or autoload.", ecosystem }; |
| 67 | } |
| 68 | |
| 69 | function cargo(files: RootFiles, text: string): Detection { |
| 70 | const ecosystem = "cargo"; |
| 71 | const lib = /^\s*\[lib\]/m.test(text) || !!files.src?.includes("lib.rs"); |
| 72 | const bin = /^\s*\[\[bin\]\]/m.test(text) || !!files.src?.includes("main.rs"); |
| 73 | if (bin) return { kind: "app", detail: "Cargo.toml builds a binary.", ecosystem }; |
| 74 | if (lib) return { kind: "library", detail: "Cargo.toml builds a library and no binary.", ecosystem }; |
| 75 | return { kind: null, detail: "Cargo.toml builds neither a library nor a binary here.", ecosystem }; |
| 76 | } |
| 77 | |
| 78 | function go(files: RootFiles): Detection { |
| 79 | const ecosystem = "go"; |
| 80 | const sources = goFilesToRead(files.entries); |
| 81 | const main = sources.find((name) => /^\s*package\s+main\b/m.test(files.text[name] ?? "")); |
| 82 | if (main) return { kind: "app", detail: `${main} at the root is package main.`, ecosystem }; |
| 83 | if (sources.length > 0) return { kind: "library", detail: "go.mod, with no package main at the root.", ecosystem }; |
| 84 | // A module whose code is all in directories: commands live in cmd/. |
| 85 | if (has(files, "cmd/")) return { kind: null, detail: "go.mod, with commands in cmd/.", ecosystem }; |
| 86 | return { kind: "library", detail: "go.mod, with no package main at the root.", ecosystem }; |
| 87 | } |
| 88 | |
| 89 | function python(text: string): Detection { |
| 90 | const ecosystem = "python"; |
| 91 | const backend = /^\s*build-backend\s*=/m.test(text) || /^\s*\[tool\.poetry\]/m.test(text); |
| 92 | const framework = PY_APP_FRAMEWORKS.find((name) => new RegExp(`["'\\s]${name}(?![\\w-])`, "i").test(text)); |
| 93 | if (framework) return { kind: "app", detail: `pyproject.toml depends on ${framework}.`, ecosystem }; |
| 94 | if (backend) return { kind: "library", detail: "pyproject.toml has a build backend and no app framework.", ecosystem }; |
| 95 | return { kind: null, detail: "pyproject.toml has no build backend.", ecosystem }; |
| 96 | } |
| 97 | |
| 98 | function npm(files: RootFiles, text: string): Detection { |
| 99 | const ecosystem = "npm"; |
| 100 | let json: { |
| 101 | scripts?: Record<string, unknown>; |
| 102 | dependencies?: Record<string, unknown>; |
| 103 | devDependencies?: Record<string, unknown>; |
| 104 | main?: unknown; |
| 105 | module?: unknown; |
| 106 | exports?: unknown; |
| 107 | files?: unknown; |
| 108 | bin?: unknown; |
| 109 | }; |
| 110 | try { |
| 111 | json = JSON.parse(text); |
| 112 | } catch { |
| 113 | return { kind: null, detail: "package.json could not be read.", ecosystem }; |
| 114 | } |
| 115 | const script = ["start", "dev"].find((name) => typeof json.scripts?.[name] === "string"); |
| 116 | if (script) return { kind: "app", detail: `package.json has a ${script} script.`, ecosystem }; |
| 117 | const deps = { ...json.devDependencies, ...json.dependencies }; |
| 118 | const framework = JS_APP_FRAMEWORKS.find((name) => name in deps); |
| 119 | if (framework) return { kind: "app", detail: `package.json depends on ${framework}.`, ecosystem }; |
| 120 | // Vite builds libraries too; with an index.html at the root it is a site. |
| 121 | if ("vite" in deps && has(files, "index.html")) return { kind: "app", detail: "A Vite site, with index.html at the root.", ecosystem }; |
| 122 | // A command to install and nothing to import: a tool. |
| 123 | if (json.bin != null && json.main == null && json.module == null && json.exports == null) { |
| 124 | return { kind: "tool", detail: 'package.json has "bin" and nothing to import.', ecosystem }; |
| 125 | } |
| 126 | const entry = ["exports", "main", "module", "files", "bin"].find((key) => json[key as keyof typeof json] != null); |
| 127 | if (entry) return { kind: "library", detail: `package.json has "${entry}" and no start or dev script.`, ecosystem }; |
| 128 | return { kind: null, detail: "package.json has no entry point or start script.", ecosystem }; |
| 129 | } |
| 130 | |
| 131 | /** |
| 132 | * What a project's root says it is. A Workers config or a root index.html |
| 133 | * is something to serve. Otherwise the first manifest present that says |
| 134 | * either way decides, the language's own before package.json, which many |
| 135 | * projects carry only for tooling. |
| 136 | */ |
| 137 | export function detectKind(files: RootFiles): Detection { |
| 138 | const workers = ["wrangler.toml", "wrangler.json", "wrangler.jsonc"].find((name) => has(files, name)); |
| 139 | if (workers) return { kind: "app", detail: `${workers} at the root.`, ecosystem: null }; |
| 140 | const docs = DOCS_CONFIGS.find((name) => has(files, name)); |
| 141 | if (docs) return { kind: "docs", detail: `${docs} at the root builds documentation.`, ecosystem: null }; |
| 142 | let first: Detection | null = null; |
| 143 | for (const name of MANIFESTS) { |
| 144 | if (!has(files, name)) continue; |
| 145 | const text = files.text[name] ?? ""; |
| 146 | const found = |
| 147 | name === "composer.json" |
| 148 | ? composer(files, text) |
| 149 | : name === "Cargo.toml" |
| 150 | ? cargo(files, text) |
| 151 | : name === "go.mod" |
| 152 | ? go(files) |
| 153 | : name === "pyproject.toml" |
| 154 | ? python(text) |
| 155 | : npm(files, text); |
| 156 | if (found.kind) return found; |
| 157 | first ??= found; |
| 158 | } |
| 159 | if (has(files, "index.html")) return { kind: "app", detail: "index.html at the root.", ecosystem: first?.ecosystem ?? null }; |
| 160 | return first ?? { kind: null, detail: "No manifest at the root says what it is.", ecosystem: null }; |
| 161 | } |
| 162 | |
| 163 | /** What resolution is given, from the project's row. */ |
| 164 | export type KindFacts = { |
| 165 | /** What a person set; null parts are left to detection. */ |
| 166 | setting: ProjectSetting; |
| 167 | /** Whether Deployments are on for it; null while unknown. */ |
| 168 | deploymentsOn: boolean | null; |
| 169 | /** Whether it has deployed production itself: a workflow's or the API's deployment, not g1t.page's, succeeded. */ |
| 170 | reportsProduction: boolean; |
| 171 | /** A package its repository publishes, other than a container image, as `Composer package psr/log`; null for none. */ |
| 172 | linkedPackage: string | null; |
| 173 | /** What its files say; null before they have been read. */ |
| 174 | detected: { kind: ProjectKind | null; detail: string } | null; |
| 175 | }; |
| 176 | |
| 177 | /** How a kind is named in a sentence: `Set in its settings: a library.` */ |
| 178 | export const KIND_PHRASE: Record<ProjectKind, string> = { |
| 179 | app: "an app", |
| 180 | library: "a library", |
| 181 | tool: "a tool", |
| 182 | docs: "documentation", |
| 183 | other: "not an app, a library, a tool or docs", |
| 184 | }; |
| 185 | |
| 186 | /** Kinds that can run somewhere: an app, and docs published as a site. */ |
| 187 | export const RUNNABLE: readonly ProjectKind[] = ["app", "docs"]; |
| 188 | |
| 189 | /** |
| 190 | * What a project is, and where it runs. The setting wins, and where it |
| 191 | * runs being set makes it an app. Left to detection: Deployments being on |
| 192 | * makes it an app; then a package its repository publishes, or files that |
| 193 | * say so, decide; anything else is an app, so nothing that deploys loses |
| 194 | * its production card to a guess. |
| 195 | * |
| 196 | * Only an app or docs runs anywhere: where it is set to; on g1t.page |
| 197 | * while Deployments are on; deploying itself once it has deployed |
| 198 | * production itself; and otherwise nobody has said (null). |
| 199 | */ |
| 200 | export function resolveKind(facts: KindFacts): { kind: ProjectKind; reason: KindReason; runs: ProjectRuns | null } { |
| 201 | const { kind, reason } = kindOf(facts); |
| 202 | const runs = RUNNABLE.includes(kind) |
| 203 | ? (facts.setting.runs ?? (facts.deploymentsOn ? "g1t" : facts.reportsProduction ? "elsewhere" : null)) |
| 204 | : null; |
| 205 | return { kind, reason, runs }; |
| 206 | } |
| 207 | |
| 208 | function kindOf(facts: KindFacts): { kind: ProjectKind; reason: KindReason } { |
| 209 | const { setting } = facts; |
| 210 | if (setting.kind) return { kind: setting.kind, reason: { by: "set", detail: `Set in its settings: ${KIND_PHRASE[setting.kind]}.` } }; |
| 211 | if (setting.runs === "g1t") return { kind: "app", reason: { by: "set", detail: "Set in its settings: it is hosted on g1t.page." } }; |
| 212 | if (setting.runs === "elsewhere") return { kind: "app", reason: { by: "set", detail: "Set in its settings: it deploys itself." } }; |
| 213 | return detectedKind(facts); |
| 214 | } |
| 215 | |
| 216 | /** What detection alone decides, whatever the setting is. */ |
| 217 | export function detectedKind(facts: Omit<KindFacts, "setting">): { kind: ProjectKind; reason: KindReason } { |
| 218 | if (facts.deploymentsOn) return { kind: "app", reason: { by: "deployments", detail: "Deployments are on for it." } }; |
| 219 | if (facts.reportsProduction) return { kind: "app", reason: { by: "deployments", detail: "It deploys production itself." } }; |
| 220 | if (facts.linkedPackage) { |
| 221 | return { kind: "library", reason: { by: "packages", detail: `Its repository publishes the ${facts.linkedPackage}.` } }; |
| 222 | } |
| 223 | if (facts.detected?.kind) return { kind: facts.detected.kind, reason: { by: "files", detail: facts.detected.detail } }; |
| 224 | return { kind: "app", reason: { by: "default", detail: "Nothing in it says what it is, so it is taken to be an app." } }; |
| 225 | } |
| 226 | |
| 227 | /** A stored or submitted kind; null (left to detection) for anything else. */ |
| 228 | export function kindSetting(value: unknown): ProjectKind | null { |
| 229 | return PROJECT_KINDS.includes(value as ProjectKind) ? (value as ProjectKind) : null; |
| 230 | } |
| 231 | |
| 232 | /** A stored or submitted place it runs; null (left to Deployments) for anything else. */ |
| 233 | export function runsSetting(value: unknown): ProjectRuns | null { |
| 234 | return value === "g1t" || value === "elsewhere" ? value : null; |
| 235 | } |
| 236 | |
| 237 | /** |
| 238 | * The setting after a change, where `auto` leaves a part to detection. A |
| 239 | * kind that never runs clears where it runs; where it runs being set on |
| 240 | * something that never runs makes it an app. |
| 241 | */ |
| 242 | export function nextSetting(current: ProjectSetting, change: { kind?: ProjectKind | "auto"; runs?: ProjectRuns | "auto" }): ProjectSetting { |
| 243 | let kind = change.kind === undefined ? current.kind : kindSetting(change.kind); |
| 244 | let runs = change.runs === undefined ? current.runs : runsSetting(change.runs); |
| 245 | if (change.kind !== undefined && kind && !RUNNABLE.includes(kind) && change.runs === undefined) runs = null; |
| 246 | if (runs && kind && !RUNNABLE.includes(kind)) kind = "app"; |
| 247 | return { kind, runs }; |
| 248 | } |
| 249 | |
| 250 | /** Whether a setting stops the project running anywhere: Deployments are turned off first. */ |
| 251 | export function neverRuns(setting: ProjectSetting): boolean { |
| 252 | return setting.kind != null && !RUNNABLE.includes(setting.kind); |
| 253 | } |