@uknows/setup 0.0.0-stage → 0.2.0

package/lib/workspace.mjs

@@ -0,0 +1,201 @@
+/*
+ * A read view of the repo plus the edits staged in this run. Producers read
+ * through it, so a later producer sees the edits of an earlier one. Nothing
+ * here writes to disk: the engine writes ws.changes() on apply.
+ *
+ * Paths are repo-relative with '/' on every OS. '.' is the root.
+ */
+import { closeSync, existsSync, lstatSync, openSync, readFileSync, readSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, posix, relative, resolve, sep } from 'node:path'
+
+/** Folders that never hold a service or deploy file of the app. Dot folders are skipped too, except .github. */
+export const SKIP_DIRS = new Set(['node_modules', 'vendor', 'venv', 'target', 'build', 'dist', 'out', 'bin', 'obj',
+  '__pycache__', 'coverage', 'test', 'tests', '__tests__', 'test_data', 'testdata', 'fixtures', 'examples', 'example', 'samples'])
+const BOM = '\uFEFF'
+const LIMIT = 20000
+
+/**
+ * @typedef {Object} Change  The net change to 1 file after every staged edit.
+ * @property {string} file
+ * @property {string|null} before   Disk text before this run, BOM removed. null = new file.
+ * @property {string} after         Text to write, BOM removed.
+ * @property {boolean} bom          The disk file starts with a UTF-8 BOM. The engine writes it back.
+ * @property {string[]} why         The why of each edit, in order.
+ */
+
+export class Workspace {
+  /** @param {string} root absolute or relative path of the repo root */
+  constructor(root) {
+    this.root = resolve(root)
+    /** @type {Map<string, string>} */ this.overlay = new Map()
+    /** @type {Map<string, string|null>} */ this.original = new Map()
+    /** @type {Map<string, string[]>} */ this.whys = new Map()
+    /** True when files() stopped at its limit. */ this.truncated = false
+  }
+
+  /** Absolute native path. */
+  abs(path) {
+    checkPath(path)
+    return path === '.' ? this.root : join(this.root, ...path.split('/'))
+  }
+
+  stat(path) {
+    try { return lstatSync(this.abs(path)) } catch { return null }
+  }
+
+  exists(path) { return this.overlay.has(path) || this.stat(path) !== null }
+
+  /** A real folder (not a link). */
+  isDir(path) { return Boolean(this.stat(path)?.isDirectory()) }
+
+  /** Current text: staged edits first, else disk. BOM removed. null when missing, a link or not a file. */
+  read(path) {
+    checkPath(path)
+    return this.overlay.has(path) ? this.overlay.get(path) : this.disk(path)
+  }
+
+  /** Text on disk, ignoring staged edits. BOM removed. */
+  disk(path) {
+    const stat = this.stat(path)
+    if (!stat?.isFile()) return null
+    const text = readFileSync(this.abs(path), 'utf8')
+    return text.startsWith(BOM) ? text.slice(1) : text
+  }
+
+  hasBom(path) {
+    if (!this.stat(path)?.isFile()) return false
+    const fd = openSync(this.abs(path), 'r')
+    try {
+      const head = Buffer.alloc(3)
+      return readSync(fd, head, 0, 3, 0) === 3 && head[0] === 0xef && head[1] === 0xbb && head[2] === 0xbf
+    } finally { closeSync(fd) }
+  }
+
+  /** Names in a folder (files and folders, links included), plus staged new files. Sorted. */
+  list(dir = '.') {
+    const names = new Set()
+    try { for (const name of readdirSync(this.abs(dir))) names.add(name) } catch { /* missing */ }
+    const prefix = dir === '.' ? '' : `${dir}/`
+    for (const path of this.overlay.keys()) {
+      if (path.startsWith(prefix) && !path.slice(prefix.length).includes('/')) names.add(path.slice(prefix.length))
+    }
+    return [...names].sort(byCodePoint)
+  }
+
+  /**
+   * Every regular file under dir, recursive, sorted. Skips links, SKIP_DIRS
+   * and dot folders except .github. Includes staged new files.
+   */
+  files(dir = '.') {
+    const out = new Set()
+    const walk = (rel) => {
+      let entries
+      try { entries = readdirSync(this.abs(rel), { withFileTypes: true }) } catch { return }
+      for (const entry of entries) {
+        if (out.size >= LIMIT) { this.truncated = true; return }
+        const path = rel === '.' ? entry.name : `${rel}/${entry.name}`
+        if (entry.isSymbolicLink()) continue
+        if (entry.isDirectory()) {
+          if (SKIP_DIRS.has(entry.name) || (entry.name.startsWith('.') && entry.name !== '.github')) continue
+          walk(path)
+        } else if (entry.isFile()) out.add(path)
+      }
+    }
+    walk(dir)
+    const prefix = dir === '.' ? '' : `${dir}/`
+    for (const path of this.overlay.keys()) if (path.startsWith(prefix)) out.add(path)
+    return [...out].sort(byCodePoint)
+  }
+
+  /**
+   * Stage an edit. Throws when edit.before is not the current text, which
+   * means 2 producers raced on the same file.
+   * @param {import('./types.mjs').Edit} edit
+   */
+  stage(edit) {
+    const current = this.read(edit.file)
+    const stale = edit.before === null ? current !== null || this.exists(edit.file) : current !== edit.before
+    if (stale) throw new Error(`Edit for ${edit.file} is out of date`)
+    if (edit.after === current) return
+    if (!this.original.has(edit.file)) this.original.set(edit.file, current)
+    this.overlay.set(edit.file, edit.after)
+    this.whys.set(edit.file, [...(this.whys.get(edit.file) ?? []), edit.why])
+  }
+
+  /** Net changes, in the order files were first staged. Files that ended up unchanged are left out. */
+  changes() {
+    const out = []
+    for (const [file, before] of this.original) {
+      const after = this.overlay.get(file)
+      if (after === before) continue
+      out.push({ file, before, after, bom: before !== null && this.hasBom(file), why: this.whys.get(file) ?? [] })
+    }
+    return out
+  }
+}
+
+/** @param {string} root */
+export const createWorkspace = (root) => new Workspace(root)
+
+/**
+ * @typedef {Object} RepoView  A read view of the whole git repo around the root, for --path runs in a monorepo.
+ * @property {() => string[]} files
+ * @property {(path: string) => string|null} read
+ * @property {(path: string) => boolean} exists
+ * @property {(path: string) => import('node:fs').Stats|null} stat
+ * @property {(dir?: string) => string[]} list   Names in 1 folder, as Workspace.list. A folder above the root reads as '../x'.
+ * @property {string} top   The repo top, relative to the root: '.', '..' or '../..'.
+ */
+
+/**
+ * The files of the whole git repo when the root is a folder inside it. Paths
+ * stay relative to the root: a file above it reads as '../../k8s/api.yaml'.
+ * Inside the root, reads go through ws, so staged edits count. Only folders
+ * up to 5 levels above the root count, and never the home folder, which can
+ * be a dotfiles repo. Nothing here writes.
+ * @param {Workspace} ws
+ * @returns {RepoView}
+ */
+export function repoView(ws) {
+  let top = null
+  for (let dir = ws.root, n = 0; n <= 5 && dir !== homedir(); dir = dirname(dir), n++) {
+    if (existsSync(join(dir, '.git'))) { top = dir; break }
+    if (dirname(dir) === dir) break
+  }
+  const view = { files: () => ws.files(), read: (path) => ws.read(path), exists: (path) => ws.exists(path), stat: (path) => ws.stat(path),
+    list: (dir = '.') => ws.list(dir), top: '.' }
+  if (!top || top === ws.root) return view
+  const outer = createWorkspace(top)
+  const prefix = relative(top, ws.root).split(sep).join('/')
+  const above = (path) => path.startsWith('../')
+  const toTop = (path) => posix.normalize(`${prefix}/${path}`)
+  let files = null
+  return {
+    files: () => (files ??= [...new Set([...ws.files(), ...outer.files().map((p) => posix.relative(prefix, p))])].sort(byCodePoint)),
+    read: (path) => (above(path) ? outer.read(toTop(path)) : ws.read(path)),
+    exists: (path) => (above(path) ? outer.exists(toTop(path)) : ws.exists(path)),
+    stat: (path) => (above(path) ? outer.stat(toTop(path)) : ws.stat(path)),
+    list: (dir = '.') => (dir === '..' || above(dir) ? outer.list(toTop(dir)) : ws.list(dir)),
+    top: prefix.split('/').map(() => '..').join('/'),
+  }
+}
+
+/** Folders from dir up to top, nearest first: upFrom('a/b', '..') is ['a/b', 'a', '.', '..']. */
+export function upFrom(dir, top = '.') {
+  const out = []
+  for (let d = dir; out.length < 64; d = d === '.' ? '..' : /^\.\.(\/\.\.)*$/.test(d) ? `${d}/..` : d.includes('/') ? d.slice(0, d.lastIndexOf('/')) : '.') {
+    out.push(d)
+    if (d === top) break
+  }
+  return out
+}
+
+export function checkPath(path) {
+  if (typeof path !== 'string' || !path || path.includes('\\') || path.startsWith('/') || /^[A-Za-z]:/.test(path)
+    || (path !== '.' && path.split('/').some((part) => !part || part === '.' || part === '..'))) {
+    throw new Error(`Not a repo-relative path: ${path}`)
+  }
+}
+
+function byCodePoint(a, b) { return a < b ? -1 : a > b ? 1 : 0 }

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@uknows/setup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Add standard OpenTelemetry to your app in 1 command, so it sends traces and logs to UKNOWS. Shows the change, asks first, can undo.",
+  "keywords": [
+    "uknows",
+    "opentelemetry",
+    "otel",
+    "apm",
+    "tracing",
+    "observability",
+    "setup",
+    "cli"
+  ],
+  "homepage": "https://uknows.my/docs",
+  "license": "Apache-2.0",
+  "author": "UKNOWS",
+  "type": "module",
+  "bin": {
+    "uknows-setup": "bin/uknows-setup.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "node tools/prepublish.mjs"
+  }
+}