@haystackeditor/cli 0.24.1 → 0.25.1

package/dist/capture/js-ast.js

@@ -0,0 +1,400 @@
+/**
+ * Babel-based reading and editing of the app's JS/TS files for capture setup (CAPTURE-V1 rule 8: init edits only what it
+ * understands). Every edit is located on the parsed AST and spliced into the original text at the node's offsets, so
+ * the customer's formatting, comments and quotes stay as they were; the result is parsed again before it is offered,
+ * and a file that does not parse after the edit is never written.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+let babel;
+/** @babel/core 8 is ESM-only; load it once before any parse (the same boundary as telemetry instrument). */
+export async function loadBabel() {
+    babel ??= await import('@babel/core');
+}
+function pluginsFor(filename) {
+    const extension = extname(filename);
+    if (extension === '.ts' || extension === '.mts' || extension === '.cts')
+        return ['typescript'];
+    if (extension === '.tsx')
+        return ['jsx', 'typescript'];
+    return ['jsx'];
+}
+/** The file's AST, or null when it does not parse (the caller reports it and leaves the file alone). */
+export function parseFile(code, filename) {
+    if (!babel)
+        throw new Error('loadBabel() must run before parseFile().');
+    try {
+        return babel.parseSync(code, {
+            filename,
+            babelrc: false,
+            configFile: false,
+            sourceType: 'unambiguous',
+            parserOpts: { plugins: pluginsFor(filename), errorRecovery: false },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** A JSON (or JSON-with-comments, like tsconfig) document as an AST: an object expression whose node offsets are offsets
+ * into `text` itself. */
+export function parseJsonLike(text, filename) {
+    const ast = parseFile(`(${text}\n)`, `${filename}.js`);
+    if (!ast)
+        return null;
+    const statement = ast.program.body[0];
+    if (ast.program.body.length !== 1 || statement?.type !== 'ExpressionStatement')
+        return null;
+    return shift(statement.expression, -1);
+}
+function shift(node, by) {
+    walk(node, current => {
+        if (typeof current.start === 'number')
+            current.start += by;
+        if (typeof current.end === 'number')
+            current.end += by;
+    });
+    return node;
+}
+/** Babel's path of `target` in `ast`, with its scopes resolved (which name a binding at that place refers to), or null. */
+export function pathOf(ast, target) {
+    if (!babel)
+        throw new Error('loadBabel() must run before pathOf().');
+    let found = null;
+    babel.traverse(ast, {
+        enter(path) {
+            if (path.node === target) {
+                found = path;
+                path.stop();
+            }
+        },
+    });
+    return found;
+}
+/** Every local name `import X from '<source>'` binds (a module may import the same default twice). */
+export function defaultImportNames(ast, source) {
+    return ast.program.body.flatMap((statement) => (statement.type === 'ImportDeclaration' && statement.source.value === source
+        && statement.importKind !== 'type'
+        ? statement.specifiers.filter((specifier) => specifier.type === 'ImportDefaultSpecifier').map((specifier) => specifier.local.name)
+        : []));
+}
+/** Depth-first over every node; `visit` returning false skips that node's children. */
+export function walk(node, visit, parent = null) {
+    if (!node || typeof node.type !== 'string')
+        return;
+    if (visit(node, parent) === false)
+        return;
+    for (const key of Object.keys(node)) {
+        if (key === 'loc' || key === 'start' || key === 'end' || key === 'extra' || key === 'leadingComments'
+            || key === 'trailingComments' || key === 'innerComments')
+            continue;
+        const value = node[key];
+        if (Array.isArray(value))
+            for (const child of value)
+                walk(child, visit, node);
+        else if (value && typeof value.type === 'string')
+            walk(value, visit, node);
+    }
+}
+export function unwrapTs(node) {
+    let current = node;
+    while (current && (current.type === 'TSAsExpression' || current.type === 'TSSatisfiesExpression'
+        || current.type === 'TSNonNullExpression' || current.type === 'ParenthesizedExpression' || current.type === 'TSTypeAssertion'
+        || current.type === 'AwaitExpression')) {
+        current = current.expression ?? current.argument;
+    }
+    return current;
+}
+export function keyName(property) {
+    if (property.computed)
+        return property.key.type === 'StringLiteral' ? property.key.value : null;
+    if (property.key.type === 'Identifier')
+        return property.key.name;
+    if (property.key.type === 'StringLiteral')
+        return property.key.value;
+    return null;
+}
+/** The top-level `const name = <init>` of the module, or null. */
+export function topLevelConst(ast, name) {
+    for (const statement of ast.program.body) {
+        const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+        if (declaration?.type !== 'VariableDeclaration')
+            continue;
+        for (const declarator of declaration.declarations) {
+            if (declarator.id.type === 'Identifier' && declarator.id.name === name && declarator.init)
+                return declarator.init;
+        }
+    }
+    return null;
+}
+export const UNREADABLE = Symbol('unreadable');
+/** The static value of an expression built only from literals, arrays, objects and top-level consts; UNREADABLE
+ * otherwise (init never evaluates the customer's code). */
+export function literalValue(node, ast, depth = 0) {
+    const current = unwrapTs(node);
+    if (!current || depth > 20)
+        return UNREADABLE;
+    switch (current.type) {
+        case 'StringLiteral':
+        case 'NumericLiteral':
+        case 'BooleanLiteral': return current.value;
+        case 'NullLiteral': return null;
+        case 'TemplateLiteral':
+            return current.expressions.length === 0 ? current.quasis.map((quasi) => quasi.value.cooked).join('') : UNREADABLE;
+        case 'Identifier': {
+            if (current.name === 'undefined')
+                return UNREADABLE;
+            const init = topLevelConst(ast, current.name);
+            return init ? literalValue(init, ast, depth + 1) : UNREADABLE;
+        }
+        case 'ArrayExpression': {
+            const values = [];
+            for (const element of current.elements) {
+                if (!element || element.type === 'SpreadElement')
+                    return UNREADABLE;
+                const value = literalValue(element, ast, depth + 1);
+                if (value === UNREADABLE)
+                    return UNREADABLE;
+                values.push(value);
+            }
+            return values;
+        }
+        case 'ObjectExpression': {
+            const value = {};
+            for (const property of current.properties) {
+                if (property.type !== 'ObjectProperty')
+                    return UNREADABLE;
+                const name = keyName(property);
+                if (name === null)
+                    return UNREADABLE;
+                const inner = literalValue(property.value, ast, depth + 1);
+                if (inner === UNREADABLE)
+                    return UNREADABLE;
+                value[name] = inner;
+            }
+            return value;
+        }
+        default: return UNREADABLE;
+    }
+}
+/** The object a config module exports: `export default <x>` / `module.exports = <x>`, through `defineConfig(...)`-style
+ * wrappers (the first argument of each call), identifiers bound to top-level consts, and functions with one returned
+ * object. null when the module's config object is not literally there. */
+export function configObject(ast) {
+    let exported = null;
+    for (const statement of ast.program.body) {
+        if (statement.type === 'ExportDefaultDeclaration')
+            exported = statement.declaration;
+        if (statement.type === 'ExpressionStatement' && statement.expression.type === 'AssignmentExpression') {
+            const left = statement.expression.left;
+            if (left.type === 'MemberExpression' && left.object.type === 'Identifier' && left.object.name === 'module'
+                && left.property.type === 'Identifier' && left.property.name === 'exports')
+                exported = statement.expression.right;
+        }
+    }
+    return exported ? unwrapConfig(exported, ast, 0) : null;
+}
+function unwrapConfig(node, ast, depth) {
+    const current = unwrapTs(node);
+    if (!current || depth > 10)
+        return null;
+    if (current.type === 'ObjectExpression')
+        return current;
+    if (current.type === 'Identifier') {
+        const init = topLevelConst(ast, current.name);
+        if (init)
+            return unwrapConfig(init, ast, depth + 1);
+        for (const statement of ast.program.body) {
+            if (statement.type === 'FunctionDeclaration' && statement.id?.name === current.name)
+                return returnedObject(statement, ast, depth);
+        }
+        return null;
+    }
+    if (current.type === 'CallExpression' && current.arguments.length > 0)
+        return unwrapConfig(current.arguments[0], ast, depth + 1);
+    if (current.type === 'ArrowFunctionExpression' || current.type === 'FunctionExpression' || current.type === 'FunctionDeclaration') {
+        return returnedObject(current, ast, depth);
+    }
+    return null;
+}
+function returnedObject(fn, ast, depth) {
+    if (fn.body.type !== 'BlockStatement')
+        return unwrapConfig(fn.body, ast, depth + 1);
+    const returns = [];
+    walk(fn.body, (node) => {
+        if (node !== fn.body && (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression'))
+            return false;
+        if (node.type === 'ReturnStatement')
+            returns.push(node);
+    });
+    return returns.length === 1 && returns[0].argument ? unwrapConfig(returns[0].argument, ast, depth + 1) : null;
+}
+/** A key path in a config module (`['kit', 'paths', 'base']`). Absent only when the path is provably absent; unreadable
+ * (a manual step for the adapter) whenever the module's config is opaque: not a literal object init can find (imported,
+ * re-exported, computed, a function with several returns), or an object on the path with a spread or a computed key that
+ * could set the key (a property counts only when it comes after every such entry; the last of duplicates wins). */
+export function readConfig(ast, path) {
+    const object = configObject(ast);
+    if (!object)
+        return { state: 'unreadable' };
+    let current = object;
+    for (const name of path) {
+        const resolved = unwrapTs(current);
+        if (resolved.type !== 'ObjectExpression')
+            return { state: 'unreadable' };
+        const members = resolved.properties;
+        let opaque = -1;
+        let found = -1;
+        members.forEach((member, index) => {
+            if (member.type === 'SpreadElement' || keyName(member) === null)
+                opaque = index;
+            else if (keyName(member) === name)
+                found = index;
+        });
+        if (found === -1)
+            return opaque === -1 ? { state: 'absent' } : { state: 'unreadable' };
+        if (found < opaque)
+            return { state: 'unreadable' };
+        const property = members[found];
+        if (property.type !== 'ObjectProperty')
+            return { state: 'unreadable' };
+        current = property.value;
+    }
+    const value = literalValue(current, ast);
+    return value === UNREADABLE ? { state: 'unreadable' } : { state: 'value', value };
+}
+export function applyEdits(code, edits) {
+    const ordered = [...edits].sort((a, b) => b.start - a.start);
+    for (let index = 1; index < ordered.length; index += 1) {
+        if (ordered[index].end > ordered[index - 1].start)
+            throw new Error('Overlapping edits.');
+    }
+    return ordered.reduce((text, edit) => `${text.slice(0, edit.start)}${edit.text}${text.slice(edit.end)}`, code);
+}
+/** The whitespace that starts the line containing `offset`. */
+export function lineIndent(code, offset) {
+    const lineStart = code.lastIndexOf('\n', offset - 1) + 1;
+    let end = lineStart;
+    while (end < code.length && (code[end] === ' ' || code[end] === '\t'))
+        end += 1;
+    return code.slice(lineStart, end);
+}
+/** True when only whitespace precedes `offset` on its line. */
+export function startsLine(code, offset) {
+    const lineStart = code.lastIndexOf('\n', offset - 1) + 1;
+    return code.slice(lineStart, offset).trim() === '';
+}
+/** The indentation unit the file uses (two spaces when it cannot tell). */
+export function indentUnit(code) {
+    for (const line of code.split('\n')) {
+        if (line.startsWith('\t'))
+            return '\t';
+        const spaces = line.length - line.trimStart().length;
+        if (spaces > 0 && line.trim() !== '' && !line.trimStart().startsWith('*'))
+            return ' '.repeat(Math.min(spaces, 4));
+    }
+    return '  ';
+}
+/** Where a new import statement goes: after the last import, else after the directive prologue ('use client'), else 0;
+ * with the text that must precede it so it starts its own line. */
+export function importInsertion(ast, code) {
+    const imports = ast.program.body.filter((statement) => statement.type === 'ImportDeclaration');
+    if (imports.length > 0)
+        return { at: imports[imports.length - 1].end, before: '\n', after: '' };
+    const directives = ast.program.directives ?? [];
+    if (directives.length > 0)
+        return { at: directives[directives.length - 1].end, before: '\n\n', after: '' };
+    return { at: 0, before: '', after: code.startsWith('\n') ? '\n' : '\n\n' };
+}
+export function jsxName(element) {
+    const name = element.openingElement?.name;
+    if (!name)
+        return null;
+    if (name.type === 'JSXIdentifier')
+        return name.name;
+    return null;
+}
+export function jsxStringAttribute(element, name) {
+    for (const attribute of element.openingElement.attributes) {
+        if (attribute.type !== 'JSXAttribute' || attribute.name.type !== 'JSXIdentifier' || attribute.name.name !== name)
+            continue;
+        const value = attribute.value;
+        if (value?.type === 'StringLiteral')
+            return value.value;
+        if (value?.type === 'JSXExpressionContainer' && value.expression.type === 'StringLiteral')
+            return value.expression.value;
+        if (value?.type === 'JSXExpressionContainer' && value.expression.type === 'TemplateLiteral' && value.expression.expressions.length === 0) {
+            return value.expression.quasis[0].value.cooked;
+        }
+    }
+    return null;
+}
+/* ------------------------------------------------------------ imports */
+const RESOLVE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.mts', '.vue', '.svelte'];
+/** tsconfig/jsconfig `compilerOptions.paths` entries of the form `prefix/*` → `dir/*` (the aliases Vite and Nuxt apps
+ * import pages through), read without following `extends`. */
+export function readPathAliases(appDir) {
+    for (const name of ['tsconfig.json', 'jsconfig.json', 'tsconfig.app.json']) {
+        const file = join(appDir, name);
+        if (!existsSync(file))
+            continue;
+        const parsed = parseJsonLike(readFileSync(file, 'utf8'), file);
+        if (!parsed)
+            continue;
+        const fake = { program: { body: [] } };
+        const value = literalValue(parsed, fake);
+        if (value === UNREADABLE || typeof value !== 'object' || value === null || Array.isArray(value))
+            continue;
+        const options = value.compilerOptions;
+        const paths = options?.paths;
+        if (!paths || typeof paths !== 'object')
+            continue;
+        const baseDir = resolve(appDir, typeof options?.baseUrl === 'string' ? options.baseUrl : '.');
+        const entries = Object.entries(paths).flatMap(([alias, targets]) => {
+            if (!alias.endsWith('/*') || !Array.isArray(targets))
+                return [];
+            const dirs = targets.filter((target) => typeof target === 'string' && target.endsWith('/*')).map(target => target.slice(0, -1));
+            return dirs.length > 0 ? [{ prefix: alias.slice(0, -1), targets: dirs }] : [];
+        });
+        if (entries.length > 0)
+            return { baseDir, entries };
+    }
+    return { baseDir: appDir, entries: [] };
+}
+function existingFile(base) {
+    const candidates = [base, ...RESOLVE_EXTENSIONS.map(extension => `${base}${extension}`),
+        ...RESOLVE_EXTENSIONS.map(extension => join(base, `index${extension}`))];
+    for (const candidate of candidates) {
+        try {
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch { /* not this candidate */ }
+    }
+    return null;
+}
+/** The file a relative or aliased import names, or null (a package import, or nothing there). */
+export function resolveImport(fromFile, specifier, aliases) {
+    if (specifier.startsWith('.'))
+        return existingFile(resolve(dirname(fromFile), specifier));
+    for (const entry of aliases.entries) {
+        if (!specifier.startsWith(entry.prefix))
+            continue;
+        for (const target of entry.targets) {
+            const found = existingFile(resolve(aliases.baseDir, target + specifier.slice(entry.prefix.length)));
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/** The source of the import that binds `local` in this module, or null. */
+export function importSourceOf(ast, local) {
+    for (const statement of ast.program.body) {
+        if (statement.type !== 'ImportDeclaration')
+            continue;
+        if (statement.specifiers.some((specifier) => specifier.local.name === local))
+            return statement.source.value;
+    }
+    return null;
+}

package/dist/capture/manifest.js

@@ -0,0 +1,95 @@
+/**
+ * The route manifest (CAPTURE-V1 rule 4) and its publication in the app's own static output.
+ *
+ * Release id: the first 16 hex of sha256(JSON.stringify({ routes, chunks })), routes in manifest order with keys in the
+ * order id, match, source, and chunks sorted: the same app rebuilt gives the same release, and ingest can recompute it.
+ * Chunk ids: the URL paths (from the origin root) of the JS files the build emitted, e.g. /_next/static/chunks/app/page-
+ * 3f1e.js or /assets/index-9ab2.js; the tag reports one only when the top frame's script URL has that path. Adapters
+ * that publish before their framework's final output exists declare none (errors then carry chunk null).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CAPTURE_MANIFEST_MAX_BYTES, CAPTURE_ROUTE_ID_MAX, CAPTURE_VERSION } from '../commands/capture-contract.js';
+import { compareRoutePatterns, parsePattern } from './route-pattern.js';
+export const MANIFEST_DIR = '.well-known/haystack-capture';
+/** Route id (rule 4): the first 16 hex of sha256(`${source}\n${match}`): the same across releases while the route's file
+ * and rule are. */
+export function routeId(source, match) {
+    return createHash('sha256').update(`${source}\n${match}`).digest('hex').slice(0, 16);
+}
+/** The routes when every one is exact; else the manual step: a widened rule would attribute visits to the wrong route,
+ * and a dropped one to a broader route (init never guesses). */
+export function exactRoutes(routes) {
+    if ('manual' in routes)
+        return routes;
+    const inexact = routes.filter(route => route.inexact);
+    if (inexact.length === 0)
+        return routes;
+    const first = inexact[0];
+    return { manual: `${inexact.length} route${inexact.length === 1 ? '' : 's'} cannot be expressed exactly in the route manifest's pattern syntax`
+            + ` (${first.source}: ${first.inexact}${inexact.length > 1 ? '; …' : ''}), so the manifest would attribute visits to the wrong routes` };
+}
+export function buildManifest(config, adapter, entries, chunks) {
+    for (const entry of entries)
+        parsePattern(entry.match);
+    const ordered = [...entries].sort((a, b) => compareRoutePatterns(a.match, b.match) || (a.rank ?? 0) - (b.rank ?? 0)
+        || (a.source < b.source ? -1 : a.source > b.source ? 1 : 0));
+    const seen = new Set();
+    const routes = ordered.filter(entry => !seen.has(entry.match) && seen.add(entry.match))
+        .map(entry => ({ id: routeId(entry.source, entry.match), match: entry.match, source: entry.source }));
+    // Rule 4: a route id is at most CAPTURE_ROUTE_ID_MAX characters; a longer one is a bug in routeId, never data to trim.
+    const tooLong = routes.find(route => route.id.length > CAPTURE_ROUTE_ID_MAX);
+    if (tooLong)
+        throw new Error(`Route id ${tooLong.id} is longer than ${CAPTURE_ROUTE_ID_MAX} characters.`);
+    const sortedChunks = [...new Set(chunks)].sort();
+    const release = createHash('sha256').update(JSON.stringify({ routes, chunks: sortedChunks })).digest('hex').slice(0, 16);
+    return {
+        version: CAPTURE_VERSION,
+        repositoryId: config.repositoryId,
+        applicationId: config.applicationId,
+        release,
+        adapter,
+        routes,
+        chunks: sortedChunks,
+    };
+}
+/** The manifest as published: refused over CAPTURE_MANIFEST_MAX_BYTES (rule 4 Publishing: the tag parses it on the page's
+ * main thread and stops for the page on a larger one). */
+export function manifestDocument(manifest) {
+    const body = `${JSON.stringify(manifest)}\n`;
+    const bytes = Buffer.byteLength(body);
+    if (bytes > CAPTURE_MANIFEST_MAX_BYTES) {
+        throw new Error(`the route manifest is ${bytes} bytes, over CAPTURE_MANIFEST_MAX_BYTES (${CAPTURE_MANIFEST_MAX_BYTES}); ${manifest.routes.length} routes and ${manifest.chunks.length} chunks`);
+    }
+    return body;
+}
+/** A file replaced in one step (written beside it, then renamed over it), so a reader never sees half of it. */
+function replaceFile(file, body) {
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, body);
+    renameSync(temporary, file);
+}
+/** Writes <release>.json and current.json (the same document) under each publish directory; returns the files written.
+ * Earlier releases' files stay (immutable): a tab still on the previous release keeps sending its release id. */
+export function writeManifest(publishDirs, manifest) {
+    const body = manifestDocument(manifest);
+    return publishDirs.flatMap(dir => {
+        const target = join(dir, MANIFEST_DIR);
+        mkdirSync(target, { recursive: true });
+        const files = [join(target, `${manifest.release}.json`), join(target, 'current.json')];
+        for (const file of files)
+            replaceFile(file, body);
+        return files;
+    });
+}
+/** A build whose manifest could not be made: its current.json files go, so no build ships a manifest of another release
+ * (the tag then records nothing on this one); <release>.json files stay. Returns the files removed. */
+export function withdrawCurrent(publishDirs) {
+    return publishDirs.map(dir => join(dir, MANIFEST_DIR, 'current.json')).filter(file => {
+        if (!existsSync(file))
+            return false;
+        unlinkSync(file);
+        return true;
+    });
+}

package/dist/capture/project.js

@@ -0,0 +1,177 @@
+/**
+ * What an adapter knows about the app before it touches anything: its package manifest, and the framework version the
+ * app actually builds with (CAPTURE-V1 rule 8b: version-aware adapters; an unknown version is a manual step). The
+ * version comes from the installed package when the checkout has one, else the lockfile's resolution, else an exact pin
+ * or a caret/tilde range in the manifest (which fixes the major, all an adapter's choices depend on).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, posix, relative, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+export function toPosix(path) {
+    return path.split(sep).join('/');
+}
+/** A path in the repository (posix), for manifest sources and messages. */
+export function repoPath(ctx, absolute) {
+    return posix.normalize(posix.join(ctx.appPath, toPosix(relative(ctx.appDir, absolute))));
+}
+/** A file of the app as the repository names it (`next.config.*` at the root, `apps/web/next.config.*` below it). */
+export function appFile(ctx, name) {
+    return posix.join(ctx.appPath, name);
+}
+export function appContext(repoRoot, appDir, appPath = toPosix(relative(repoRoot, appDir)) || '.') {
+    return { repoRoot, appDir, appPath, pkg: readPackageJson(appDir) };
+}
+export function readPackageJson(dir) {
+    const file = join(dir, 'package.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function declaredRange(pkg, name) {
+    return pkg?.dependencies?.[name] ?? pkg?.devDependencies?.[name] ?? null;
+}
+function dirsUp(from, to) {
+    const dirs = [];
+    let current = from;
+    for (;;) {
+        dirs.push(current);
+        if (current === to || relative(to, current).startsWith('..'))
+            break;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+function exact(version, from) {
+    const match = /^(\d+)\.\d+\.\d+/.exec(version);
+    return { version, major: match ? Number(match[1]) : null, from };
+}
+function fromRange(range) {
+    const trimmed = range.trim().replace(/^npm:[^@]+@/, '');
+    const match = /^[\^~]?(\d+)(?:\.(?:\d+|x|\*))*$/.exec(trimmed);
+    return { version: range, major: match ? Number(match[1]) : null, from: 'package.json' };
+}
+/** Parsed lockfiles by path: discovery reads the same monorepo lockfile for every package. */
+const pnpmLocks = new Map();
+function fromPnpmLock(file, importer, name) {
+    let lock = pnpmLocks.get(file);
+    if (!lock) {
+        lock = parseYaml(readFileSync(file, 'utf8'), { maxAliasCount: -1 });
+        pnpmLocks.set(file, lock);
+    }
+    const entry = lock.importers?.[importer];
+    const dependency = entry?.dependencies?.[name] ?? entry?.devDependencies?.[name];
+    const version = typeof dependency === 'string' ? dependency : dependency?.version;
+    if (!version || version.startsWith('link:'))
+        return null;
+    return version.split('(')[0];
+}
+function fromPackageLock(file, importer, name) {
+    const lock = JSON.parse(readFileSync(file, 'utf8'));
+    const nested = importer === '.' ? null : lock.packages?.[`${importer}/node_modules/${name}`]?.version;
+    return nested ?? lock.packages?.[`node_modules/${name}`]?.version ?? lock.dependencies?.[name]?.version ?? null;
+}
+/** yarn.lock (v1 and berry): the entry whose header lists `<name>@<range>`. */
+function fromYarnLock(file, name, range) {
+    const wanted = new Set([`${name}@${range}`, `${name}@npm:${range}`]);
+    let inEntry = false;
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        if (line !== '' && !line.startsWith(' ') && !line.startsWith('#')) {
+            const specs = line.replace(/:$/, '').split(',').map(spec => spec.trim().replace(/^"|"$/g, ''));
+            inEntry = specs.some(spec => wanted.has(spec));
+            continue;
+        }
+        const version = inEntry ? /^ {2}version:? "?([^"\s]+)"?$/.exec(line) : null;
+        if (version)
+            return version[1];
+    }
+    return null;
+}
+/** The version of `name` the app builds with, or null when the app does not depend on it. */
+export function resolveVersion(ctx, name) {
+    const range = declaredRange(ctx.pkg, name);
+    if (range === null)
+        return null;
+    const dirs = dirsUp(ctx.appDir, ctx.repoRoot);
+    for (const dir of dirs) {
+        const installed = join(dir, 'node_modules', name, 'package.json');
+        if (!existsSync(installed))
+            continue;
+        try {
+            const version = JSON.parse(readFileSync(installed, 'utf8')).version;
+            if (version)
+                return exact(version, repoPath(ctx, installed));
+        }
+        catch { /* an unreadable install says nothing; the lockfile decides */ }
+    }
+    for (const dir of dirs) {
+        const importer = toPosix(relative(dir, ctx.appDir)) || '.';
+        const readers = [
+            ['pnpm-lock.yaml', () => fromPnpmLock(join(dir, 'pnpm-lock.yaml'), importer, name)],
+            ['package-lock.json', () => fromPackageLock(join(dir, 'package-lock.json'), importer, name)],
+            ['yarn.lock', () => fromYarnLock(join(dir, 'yarn.lock'), name, range)],
+        ];
+        for (const [lockfile, read] of readers) {
+            if (!existsSync(join(dir, lockfile)))
+                continue;
+            let version = null;
+            try {
+                version = read();
+            }
+            catch {
+                version = null;
+            }
+            if (version)
+                return exact(version, repoPath(ctx, join(dir, lockfile)));
+            // One lockfile per install root: a lockfile that does not resolve it leaves the manifest's range to decide.
+            return /^\d+\.\d+\.\d+$/.test(range) ? exact(range, 'package.json') : fromRange(range);
+        }
+    }
+    return /^\d+\.\d+\.\d+$/.test(range) ? exact(range, 'package.json') : fromRange(range);
+}
+/** Gemfile.lock's resolved version of a gem (`    rails (7.1.3)` under specs). */
+export function gemVersion(appDir, gem) {
+    const file = join(appDir, 'Gemfile.lock');
+    if (!existsSync(file))
+        return null;
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        const match = /^ {4}([A-Za-z0-9_.-]+) \(([^)]+)\)$/.exec(line);
+        if (match && match[1] === gem)
+            return exact(match[2], 'Gemfile.lock');
+    }
+    return null;
+}
+/** Django's version from the app's lockfile or pinned requirements. */
+export function djangoVersion(appDir) {
+    for (const lockfile of ['uv.lock', 'poetry.lock']) {
+        const file = join(appDir, lockfile);
+        if (!existsSync(file))
+            continue;
+        const lines = readFileSync(file, 'utf8').split('\n');
+        for (let index = 0; index < lines.length - 1; index += 1) {
+            if (/^name = "django"$/i.test(lines[index].trim())) {
+                const version = /^version = "([^"]+)"$/.exec(lines[index + 1].trim());
+                if (version)
+                    return exact(version[1], lockfile);
+            }
+        }
+    }
+    for (const requirements of ['requirements.txt', 'requirements/base.txt', 'requirements/production.txt']) {
+        const file = join(appDir, requirements);
+        if (!existsSync(file))
+            continue;
+        for (const line of readFileSync(file, 'utf8').split('\n')) {
+            const pinned = /^django==(\d+\.\d+(?:\.\d+)?)\b/i.exec(line.trim());
+            if (pinned)
+                return { version: pinned[1], major: Number(pinned[1].split('.')[0]), from: requirements };
+        }
+    }
+    return null;
+}