@alecsibilia/luca 14.0.0-alpha.2 → 14.0.0-alpha.21

package/engine/gates/leftover-scan.ts

@@ -1,6 +1,10 @@
 import { basename, extname } from 'node:path'
 
-import type { LeftoverHit } from './gate-schemas'
+import type {
+    LeftoverHit,
+    LeftoverPass,
+    LeftoverPassReason,
+} from './gate-schemas'
 
 import type { FileChange } from '../git/git-adapter'
 
@@ -21,6 +25,35 @@ const CODE_EXTENSIONS = new Set([
 const TOOL_LEFTOVER = /\.(log|orig|rej|bak|swp|swo|tmp|temp)$/i
 const SCRATCH_NAME =
     /^(tmp|temp|scratch|scratchpad|debug|notes?|todo)([-_.]|$)/i
+const SCRATCH_REASON = 'a scratch file'
+const MARKDOWN_REASON = 'a new markdown file the spec and ticket do not name'
+
+/**
+ * Files a tool or framework loads by name, so nothing imports them: tool
+ * configs (`vite.config.ts`, `eslint.config.mjs`), framework entry, root,
+ * routes, and middleware files, and anything in a file-based router's
+ * folder.
+ */
+const LOADED_BY_NAME = [
+    /\.config\.(ts|js|mjs|cjs|mts|cts)$/i,
+    /^entry\.(server|client)\./i,
+    /^(root|routes|middleware)\./i,
+]
+const ROUTER_FOLDER = /(^|\/)(app\/routes|pages|src\/app|src\/pages)\//
+
+/**
+ * A changeset an agent wrote: a new markdown file in `.changeset/` other than
+ * its README. The engine writes the run's one changeset itself.
+ */
+export const isAgentChangeset = ({ path, change }: FileChange): boolean =>
+    change === 'added' &&
+    /^\.changeset\/[^/]+\.md$/.test(path) &&
+    basename(path) !== 'README.md'
+
+/** Whether a tool or framework loads this file by its name or folder. */
+const loadedByName = (path: string): boolean =>
+    LOADED_BY_NAME.some((pattern) => pattern.test(basename(path))) ||
+    ROUTER_FOLDER.test(path)
 
 /** A new code file's name without its extension, as imports name it. */
 export const importStem = (path: string): string =>
@@ -40,6 +73,42 @@ export const newCodeFiles = ({
         .filter((path) => CODE_EXTENSIONS.has(extname(path).toLowerCase()))
         .filter((path) => !test_files.includes(path))
         .filter((path) => importStem(path) !== 'index')
+        .filter((path) => !loadedByName(path))
+
+const isNewMarkdown = ({ path, change }: FileChange): boolean =>
+    change === 'added' && extname(path).toLowerCase() === '.md'
+
+/** Folders whose markdown is docs the repo asks for, at any depth (#520). */
+const DOC_FOLDERS = new Set(['docs', 'adr'])
+
+/** Whether a markdown file is a `README.md` or sits in a doc folder. */
+const inDocPlace = (path: string): boolean =>
+    basename(path) === 'README.md' ||
+    path
+        .split('/')
+        .slice(0, -1)
+        .some((folder) => DOC_FOLDERS.has(folder))
+
+/**
+ * Files the "named by the repo" rule can clear: scratch-named files, and
+ * new markdown outside a doc place (#520). Each needs a "does a tracked or
+ * newly added non-test file name it?" answer. (A new code file needs none:
+ * its basename holds its import stem, so a file that names it already
+ * makes it used.)
+ */
+export const nameCheckedFiles = ({
+    changes,
+}: {
+    changes: FileChange[]
+}): string[] =>
+    changes
+        .filter(
+            (file) =>
+                (file.change !== 'deleted' &&
+                    SCRATCH_NAME.test(basename(file.path))) ||
+                (isNewMarkdown(file) && !inDocPlace(file.path))
+        )
+        .map(({ path }) => path)
 
 const nameHit = (path: string): string | null => {
     // git lists a folder with its own repo as one path ending in a slash.
@@ -51,13 +120,71 @@ const nameHit = (path: string): string | null => {
     if (TOOL_LEFTOVER.test(name) || name.endsWith('~')) {
         return 'a log, backup, or merge leftover'
     }
-    if (SCRATCH_NAME.test(name)) return 'a scratch file'
+    if (SCRATCH_NAME.test(name)) return SCRATCH_REASON
     if (/^junit.*\.xml$/i.test(name) || path.startsWith('coverage/')) {
         return 'test tool output'
     }
     return null
 }
 
+/** The leftover scan's inputs; see `scanLeftovers`. */
+type ScanInputs = {
+    changes: FileChange[]
+    test_files: string[]
+    mention_text: string
+    used_code: Record<string, boolean>
+    named?: string[]
+    leftover_allow?: string[]
+}
+
+/** Why a new markdown file the spec and ticket don't name may stay, if it may. */
+const markdownPass = ({
+    path,
+    named,
+    leftover_allow,
+}: {
+    path: string
+    named: string[]
+    leftover_allow: string[]
+}): LeftoverPassReason | null => {
+    if (inDocPlace(path)) return 'doc_place'
+    if (named.includes(path)) return 'named_by_repo'
+    if (leftover_allow.some((pattern) => new Bun.Glob(pattern).match(path))) {
+        return 'config_pattern'
+    }
+    return null
+}
+
+/** The hits and passes among the changed files, before new code's use. */
+const fileVerdicts = ({
+    changes,
+    mention_text,
+    named = [],
+    leftover_allow = [],
+}: ScanInputs): { hits: LeftoverHit[]; passes: LeftoverPass[] } => {
+    const hits: LeftoverHit[] = []
+    const passes: LeftoverPass[] = []
+    for (const file of changes) {
+        const { path } = file
+        if (file.change === 'deleted') continue
+        const hit = nameHit(path)
+        // A module the repo names, such as a TOC's `debug.lua`, isn't scratch.
+        const reason =
+            hit === SCRATCH_REASON && named.includes(path) ? null : hit
+        if (reason !== null) hits.push({ path, reason })
+        else if (
+            isNewMarkdown(file) &&
+            !mention_text.includes(basename(path))
+        ) {
+            const pass = markdownPass({ path, named, leftover_allow })
+            if (pass === null) {
+                hits.push({ path, reason: MARKDOWN_REASON })
+            } else passes.push({ path, reason: pass })
+        }
+    }
+    return { hits, passes }
+}
+
 /**
  * The leftover scan. Pure: given a worktree's changes, it lists the files the
  * engine must not commit. It runs before every engine commit.
@@ -65,44 +192,28 @@ const nameHit = (path: string): string | null => {
  * Blocks scratch files, logs, `.orig` and other tool leftovers, `.DS_Store`,
  * new markdown the spec and ticket don't name, new scripts or modules
  * that nothing uses, and a folder with its own git repo in it (which
- * `git add` can't take as files).
+ * `git add` can't take as files). A file a tool or framework loads by name
+ * (`*.config.*`, `entry.server.*`, a route file) is never "unused", and a
+ * scratch-named file the repo names is not scratch. New markdown in a doc
+ * place, named by the repo, or matching `leftover_allow` passes (#520; see
+ * `leftoverPasses`).
  *
  * @param mention_text - The spec's and ticket's text; a new markdown file is
  *   fine if it names the file.
  * @param used_code - For each of `newCodeFiles(...)`, whether another file
  *   mentions it.
+ * @param named - Those of `nameCheckedFiles(...)` whose basename a tracked
+ *   or newly added non-test file names (a TOC, `package.json`, a config).
+ * @param leftover_allow - The config's glob patterns for more new markdown
+ *   to let through.
  *
  * @example
- * const hits = scanLeftovers({ changes, test_files, mention_text, used_code })
+ * const hits = scanLeftovers({ changes, test_files, mention_text, used_code, named })
  * if (hits.length > 0) console.error(hits)
  */
-export const scanLeftovers = ({
-    changes,
-    test_files,
-    mention_text,
-    used_code,
-}: {
-    changes: FileChange[]
-    test_files: string[]
-    mention_text: string
-    used_code: Record<string, boolean>
-}): LeftoverHit[] => {
-    const hits: LeftoverHit[] = []
-    for (const { path, change } of changes) {
-        if (change === 'deleted') continue
-        const reason = nameHit(path)
-        if (reason !== null) hits.push({ path, reason })
-        else if (
-            change === 'added' &&
-            extname(path).toLowerCase() === '.md' &&
-            !mention_text.includes(basename(path))
-        ) {
-            hits.push({
-                path,
-                reason: 'a new markdown file the spec and ticket do not name',
-            })
-        }
-    }
+export const scanLeftovers = (inputs: ScanInputs): LeftoverHit[] => {
+    const { changes, test_files, used_code } = inputs
+    const { hits } = fileVerdicts(inputs)
     for (const path of newCodeFiles({ changes, test_files })) {
         if (used_code[path] === false) {
             hits.push({
@@ -113,3 +224,15 @@ export const scanLeftovers = ({
     }
     return hits
 }
+
+/**
+ * The new markdown files `scanLeftovers` let through on the same inputs,
+ * each with why (#520), for the journal. Markdown the spec or ticket names
+ * isn't listed: it always passed.
+ *
+ * @example
+ * leftoverPasses({ ...inputs, changes: [{ path: 'docs/adr/0001.md', change: 'added' }] })
+ * // [{ path: 'docs/adr/0001.md', reason: 'doc_place' }]
+ */
+export const leftoverPasses = (inputs: ScanInputs): LeftoverPass[] =>
+    fileVerdicts(inputs).passes

package/engine/gates/new-tests.ts

@@ -0,0 +1,45 @@
+/**
+ * Test names in a test file's text (#581): the plain string names of `test`
+ * and `it` calls (with `.only`, `.skip`, `.todo`, `.failing`), in any quote.
+ * A template name with `${}` and a `test.each` table are left out: their
+ * names aren't known until they run. The test-writer must use plain names.
+ * A call on something else, like `pattern.test('abc')`, is not a test. This
+ * is a text scan, not a parse, so a `test('...')` inside a string or comment
+ * of a changed file counts as a test name. The red check trusts the scan
+ * alone only for a file that doesn't load yet; for a file that ran, it keeps
+ * just the names of cases that ran.
+ *
+ * @example
+ * testNamesIn({ source: "test('adds', () => {})" }) // ['adds']
+ */
+export const testNamesIn = ({ source }: { source: string }): string[] => {
+    const names: string[] = []
+    const call =
+        /(?<![\w$.])(?:test|it)(?:\.(?:only|skip|todo|failing|concurrent|serial))?\(\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1/g
+    for (const match of source.matchAll(call)) {
+        const [, quote, raw = ''] = match
+        if (quote === '`' && raw.includes('${')) continue
+        names.push(raw.replace(/\\(.)/g, '$1'))
+    }
+    return names
+}
+
+/**
+ * The test names a change added to one test file (#581): names in `current`
+ * that `base` doesn't have. A new file (`base` null) adds all of its names;
+ * a deleted one (`current` null) adds none.
+ *
+ * @example
+ * addedTestNames({ base: "test('a', () => {})", current: "test('a', () => {}); test('b', () => {})" }) // ['b']
+ */
+export const addedTestNames = ({
+    base,
+    current,
+}: {
+    base: string | null
+    current: string | null
+}): string[] => {
+    if (current === null) return []
+    const before = new Set(base === null ? [] : testNamesIn({ source: base }))
+    return testNamesIn({ source: current }).filter((name) => !before.has(name))
+}

package/engine/gates/own-files-check.ts

@@ -0,0 +1,98 @@
+/**
+ * The ticket's own test files (#564): the changed test files no fast `bun`
+ * run gave results for, run on their own with plain `bun test` as one more
+ * `test` check, after the fast runs.
+ */
+import type { GateCheck, TestCase, TestRun } from './gate-schemas'
+import { msSince } from './shell-check'
+import {
+    fileTestsCommand,
+    reportFileFor,
+    runTestsInHeldSlot,
+} from './test-runner'
+import { inTestSlot } from './test-slots'
+
+/**
+ * Runs the `own_test_files` that every fast run left without results (a file
+ * with no fast `bun` run at all has no run to have left it out, so it is not
+ * one) with plain `bun test`, in a test slot (#544), with the test commands'
+ * time limit.
+ *
+ * Returns the run's test cases, and its check: `null` when there was nothing
+ * to run, or when the run gave no results at all (its files don't load) after
+ * a failed fast run. That is no news (the gate fails anyway, and the slow
+ * file's load error shows on the next run, once that is fixed); with every
+ * fast run passing, it is a real failure of its own.
+ *
+ * @example
+ * const { check, cases } = await ownFilesCheck({ own_test_files, fast_checks, fast_runs, cwd, report_file, report_index, timeout_ms, test_concurrency, exclusive })
+ */
+export const ownFilesCheck = async ({
+    own_test_files,
+    fast_checks,
+    fast_runs,
+    cwd,
+    report_file,
+    report_index,
+    timeout_ms,
+    test_concurrency,
+    exclusive,
+}: {
+    /** The ticket's changed test files. */
+    own_test_files: string[]
+    /** The fast test checks, already run. */
+    fast_checks: GateCheck[]
+    /** The fast `bun` runs, already done. */
+    fast_runs: TestRun[]
+    cwd: string
+    report_file: string
+    /** The index for this run's own report file. */
+    report_index: number
+    timeout_ms: number
+    /** The config's `test_concurrency`; left out, no cap. */
+    test_concurrency: number | undefined
+    exclusive: boolean
+}): Promise<{ check: GateCheck | null; cases: TestCase[] }> => {
+    // A file with no fast bun run at all has no run to have given it results,
+    // so it is not one the fast run left out.
+    const unrun = own_test_files.filter(
+        (file) =>
+            fast_runs.length > 0 &&
+            fast_runs.every(({ files_without_results }) =>
+                files_without_results.includes(file)
+            )
+    )
+    if (unrun.length === 0) return { check: null, cases: [] }
+    const { run, ...check } = await inTestSlot({
+        test_concurrency,
+        exclusive,
+        work: async () => {
+            const started = performance.now()
+            const run = await runTestsInHeldSlot({
+                cwd,
+                command: fileTestsCommand({ files: unrun }),
+                test_files: unrun,
+                report_file: reportFileFor({
+                    report_file,
+                    index: report_index,
+                }),
+                timeout_ms,
+            })
+            const check: GateCheck = {
+                name: 'test',
+                command: run.command,
+                ok: run.ok,
+                exit_code: run.exit_code,
+                output: run.ok ? '' : run.output,
+                duration_ms: msSince(started),
+            }
+            return { ...check, run }
+        },
+    })
+    // A run with no results at all means its files don't load. After a
+    // failed fast run that is no news (the gate fails anyway, and the slow
+    // file's load error shows on the next run, once that is fixed);
+    // with every fast run passing, it is a real failure of its own.
+    const counts = run.cases.length > 0 || fast_checks.every(({ ok }) => ok)
+    return { check: counts ? check : null, cases: run.cases }
+}

package/engine/gates/prepare-check.ts

@@ -0,0 +1,60 @@
+/**
+ * The prepare check: the config's prepare command, run before every test run
+ * in a checkout, one at a time per the config's `prepare_concurrency`.
+ */
+import type { GateCheck } from './gate-schemas'
+import { PREPARE_SLOTS } from './prepare-slots'
+import { msSince, shellCheck } from './shell-check'
+import { onSlotWait } from './slot-waits'
+
+import {
+    prepareConcurrencyOf,
+    prepareTimeoutOf,
+    type EngineConfig,
+} from '../config/engine-config'
+
+/**
+ * Runs the config's prepare command in `cwd`, as the `prepare` check, or
+ * `null` when the config has none. The engine runs it before every test run
+ * in a checkout, so tests that need build outputs find them up to date.
+ * It gets its own time limit (see `prepareTimeoutOf`), since a first build
+ * can take far longer than other commands.
+ *
+ * At most `prepareConcurrencyOf` prepare runs go at once in the engine (see
+ * `PREPARE_SLOTS`); the rest wait their turn. The time limit starts when a
+ * run starts, so waiting for a turn never counts toward it. The check says
+ * how long it waited for its turn, as `wait_ms` (#518), and the step's
+ * slot-wait listener hears the wait while it lasts (see `slot-waits.ts`).
+ *
+ * @example
+ * const prepare = await prepareCheck({ config, cwd })
+ * if (prepare !== null && !prepare.ok) console.log(prepare.output)
+ */
+export const prepareCheck = async ({
+    config,
+    cwd,
+}: {
+    config: EngineConfig
+    cwd: string
+}): Promise<GateCheck | null> => {
+    const { prepare } = config
+    if (prepare === undefined) return null
+    const asked = performance.now()
+    const limit = prepareConcurrencyOf({ config })
+    return PREPARE_SLOTS.run({
+        limit,
+        on_wait: onSlotWait({ kind: 'prepare_slot', limit }),
+        work: async () => {
+            const wait_ms = msSince(asked)
+            const check = await shellCheck({
+                name: 'prepare',
+                command: prepare,
+                cwd,
+                timeout_ms: prepareTimeoutOf({ config }),
+                timeout_hint:
+                    'To give it longer, raise `prepare_timeout_ms` in `.luca/config.json`.',
+            })
+            return { ...check, wait_ms }
+        },
+    })
+}

package/engine/gates/prepare-slots.ts

@@ -0,0 +1,99 @@
+/** Runs work once a slot is free, and frees the slot when it settles. */
+export type Slots = {
+    /**
+     * Waits for a slot (at most `limit` pieces of work at once), then runs
+     * `work`. The slot is freed when `work` settles, even when it throws.
+     * An `exclusive` take waits until no work holds a slot, then holds them
+     * all: nothing else starts until it settles. A take that must wait
+     * calls `on_wait` with the slots in use, and what that gives back once
+     * the slot is taken.
+     */
+    run: <T>(args: {
+        limit: number
+        work: () => Promise<T>
+        exclusive?: boolean
+        on_wait?: (in_use: number) => () => void
+    }) => Promise<T>
+    /** How many pieces of work hold a slot now. */
+    busy: () => number
+}
+
+/**
+ * A counting semaphore: at most `limit` pieces of work at once, the rest
+ * wait their turn in call order. Each call names its own `limit`, so a
+ * later call can raise or lower it; a lower limit lets nothing new start
+ * until enough work has finished. An `exclusive` call (#544) waits for
+ * every running piece to end, and the work queued behind it waits for it.
+ *
+ * @example
+ * const slots = createSlots()
+ * await Promise.all([
+ *     slots.run({ limit: 1, work: () => build('a') }),
+ *     slots.run({ limit: 1, work: () => build('b') }), // starts once 'a' ends
+ * ])
+ */
+export const createSlots = (): Slots => {
+    let taken = 0
+    let alone = false
+    const waiting: { limit: number; exclusive: boolean; start: () => void }[] =
+        []
+
+    const startWaiting = () => {
+        while (waiting.length > 0 && !alone) {
+            const [next] = waiting
+            if (next === undefined) return
+            if (next.exclusive ? taken > 0 : taken >= next.limit) return
+            waiting.shift()
+            taken += 1
+            alone = next.exclusive
+            next.start()
+        }
+    }
+
+    const take = ({
+        limit,
+        exclusive,
+        on_wait,
+    }: {
+        limit: number
+        exclusive: boolean
+        on_wait: ((in_use: number) => () => void) | undefined
+    }): Promise<void> => {
+        let started = false
+        const taken_now = new Promise<void>((start) => {
+            waiting.push({
+                limit,
+                exclusive,
+                start: () => {
+                    started = true
+                    start()
+                },
+            })
+            startWaiting()
+        })
+        if (started || on_wait === undefined) return taken_now
+        const slot_taken = on_wait(taken)
+        return taken_now.then(() => slot_taken())
+    }
+
+    return {
+        run: async ({ limit, work, exclusive = false, on_wait }) => {
+            await take({ limit, exclusive, on_wait })
+            try {
+                return await work()
+            } finally {
+                taken -= 1
+                if (exclusive) alone = false
+                startWaiting()
+            }
+        },
+        busy: () => taken,
+    }
+}
+
+/**
+ * The engine's prepare slots: one set for the whole engine process, so the
+ * cap spans every ticket that builds at the same time. A `luca` process runs
+ * one run, so in practice the cap is the run's.
+ */
+export const PREPARE_SLOTS: Slots = createSlots()