codz-cli 0.0.0-stage → 0.1.2

package/dist/core/jsonEdit.js

@@ -0,0 +1,113 @@
+// Small edits to JSON text that keep the rest of the file byte for byte:
+// set one (possibly nested) key without reformatting anything else.
+import { ToolError } from "./types.js";
+function ws(t, i) {
+    while (i < t.length && /\s/.test(t[i]))
+        i++;
+    return i;
+}
+function parseString(t, i) {
+    let j = i + 1;
+    while (j < t.length && t[j] !== '"')
+        j += t[j] === '\\' ? 2 : 1;
+    return [JSON.parse(t.slice(i, j + 1)), j + 1];
+}
+function parseValue(t, i) {
+    i = ws(t, i);
+    const c = t[i];
+    if (c === '{') {
+        const object = parseObject(t, i);
+        return { end: object.close + 1, object };
+    }
+    if (c === '"')
+        return { end: parseString(t, i)[1] };
+    if (c === '[') {
+        let j = ws(t, i + 1);
+        if (t[j] === ']')
+            return { end: j + 1 };
+        for (;;) {
+            j = ws(t, parseValue(t, j).end);
+            if (t[j] === ',')
+                j++;
+            else if (t[j] === ']')
+                return { end: j + 1 };
+            else
+                throw new ToolError('bad_json', `Unexpected "${t[j]}" at offset ${j}.`);
+        }
+    }
+    const m = /^(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)/.exec(t.slice(i));
+    if (!m)
+        throw new ToolError('bad_json', `Unexpected "${c}" at offset ${i}.`);
+    return { end: i + m[0].length };
+}
+function parseObject(t, open) {
+    const members = [];
+    let i = ws(t, open + 1);
+    if (t[i] === '}')
+        return { open, close: i, members };
+    for (;;) {
+        if (t[i] !== '"')
+            throw new ToolError('bad_json', `Expected a key at offset ${i}.`);
+        const [key, afterKey] = parseString(t, i);
+        let j = ws(t, afterKey);
+        if (t[j] !== ':')
+            throw new ToolError('bad_json', `Expected ":" at offset ${j}.`);
+        const valueStart = ws(t, j + 1);
+        const v = parseValue(t, valueStart);
+        members.push({ key, start: i, valueStart, valueEnd: v.end, object: v.object });
+        j = ws(t, v.end);
+        if (t[j] === ',')
+            i = ws(t, j + 1);
+        else if (t[j] === '}')
+            return { open, close: j, members };
+        else
+            throw new ToolError('bad_json', `Unexpected "${t[j]}" at offset ${j}.`);
+    }
+}
+const lineIndent = (t, pos) => t.slice(t.lastIndexOf('\n', pos - 1) + 1).match(/^[ \t]*/)[0];
+function indentUnit(t) {
+    const m = /\n([ \t]+)"/.exec(t);
+    return m ? (m[1][0] === '\t' ? '\t' : ' '.repeat(Math.min(m[1].length, 8))) : '  ';
+}
+function render(value, indent, unit) {
+    return JSON.stringify(value, null, unit).replace(/\n/g, `\n${indent}`);
+}
+function insert(t, obj, key, value, unit) {
+    const oneLine = !t.slice(obj.open, obj.close).includes('\n') && obj.members.length > 0;
+    if (oneLine) {
+        const last = obj.members[obj.members.length - 1];
+        return `${t.slice(0, last.valueEnd)}, ${JSON.stringify(key)}: ${JSON.stringify(value)}${t.slice(last.valueEnd)}`;
+    }
+    const indent = obj.members.length ? lineIndent(t, obj.members[0].start) : lineIndent(t, obj.close) + unit;
+    const entry = `${JSON.stringify(key)}: ${render(value, indent, unit)}`;
+    if (!obj.members.length)
+        return `${t.slice(0, obj.open + 1)}\n${indent}${entry}\n${lineIndent(t, obj.close)}${t.slice(obj.close)}`;
+    const last = obj.members[obj.members.length - 1];
+    return `${t.slice(0, last.valueEnd)},\n${indent}${entry}${t.slice(last.valueEnd)}`;
+}
+/** Sets path (nested keys) to value, creating parent objects as needed. */
+export function jsonSet(text, path, value) {
+    const start = ws(text, 0);
+    if (text[start] !== '{')
+        throw new ToolError('bad_json', 'The file is not a JSON object.');
+    const unit = indentUnit(text);
+    let obj = parseObject(text, start);
+    for (let i = 0; i < path.length; i++) {
+        const m = obj.members.find((x) => x.key === path[i]);
+        const last = i === path.length - 1;
+        if (!m) {
+            let v = value;
+            for (const k of path.slice(i + 1).reverse())
+                v = { [k]: v };
+            return insert(text, obj, path[i], v, unit);
+        }
+        if (last) {
+            const indent = lineIndent(text, m.start);
+            return text.slice(0, m.valueStart) + render(value, indent, unit) + text.slice(m.valueEnd);
+        }
+        if (!m.object)
+            throw new ToolError('key_conflict', `${path.slice(0, i + 1).join('.')} is a text, so it cannot hold ${path.join('.')}.`, 'Pick another key name.');
+        obj = m.object;
+    }
+    return text;
+}

package/dist/core/merge.js

@@ -0,0 +1,159 @@
+// Keeps hand-written code when codz regenerates a model.
+//
+// Dart: a regenerated class gets back every member codz does not generate
+// (copyWith, ==, hashCode, toString, getters, other constructors and methods).
+// TypeScript: doc comments above interface fields survive.
+import { matchBrace, maskCode } from "../adapters/source.js";
+function classBlocks(text, masked) {
+    const out = new Map();
+    for (const m of masked.matchAll(/\bclass\s+(\w+)[^{;]*\{/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchBrace(text, open, 'dart');
+        if (close !== -1)
+            out.set(m[1], { open, close });
+    }
+    return out;
+}
+/** Splits a Dart class body into members, each with the comments and annotations above it. */
+export function splitDartMembers(body) {
+    const masked = maskCode(body, 'dart');
+    const out = [];
+    let start = 0;
+    let i = 0;
+    let depth = 0;
+    const push = (end) => {
+        const text = body.slice(start, end);
+        if (text.trim()) {
+            const code = masked.slice(start, end);
+            out.push({ text, code, name: memberName(code) });
+        }
+        start = end;
+    };
+    while (i < body.length) {
+        const c = masked[i];
+        if (c === '(' || c === '[' || c === '{')
+            depth++;
+        else if (c === ')' || c === ']' || c === '}') {
+            depth--;
+            if (depth === 0 && c === '}') {
+                // A block body ends the member unless an expression continues (`= {...};`, `}.foo`, `},`).
+                let j = i + 1;
+                while (j < body.length && /\s/.test(masked[j]))
+                    j++;
+                if (masked[j] === ';') {
+                    i = j;
+                    push(i + 1);
+                }
+                else if (!/[.,)?:]/.test(masked[j] ?? ''))
+                    push(i + 1);
+            }
+        }
+        else if (c === ';' && depth === 0)
+            push(i + 1);
+        i++;
+    }
+    if (body.slice(start).trim())
+        push(body.length);
+    return out;
+}
+function memberName(code) {
+    const c = code.replace(/@\w+(\([^)]*\))?/g, '').trim();
+    const getter = /\b(?:get|set)\s+(\w+)/.exec(c);
+    if (getter)
+        return getter[1];
+    if (/\boperator\s*==/.test(c))
+        return 'operator ==';
+    const call = /([\w.]+)\s*(?:<[^>]*>)?\s*\(/.exec(c);
+    const field = /(\w+)\s*(?:=|;)/.exec(c);
+    if (call && (!field || call.index < field.index))
+        return call[1];
+    return field ? field[1] : c.split(/\s+/).slice(-1)[0];
+}
+/** True for members codz writes itself in a model class. */
+function isGenerated(m, cls) {
+    const c = m.code.replace(/@\w+(\([^)]*\))?/g, '').trim();
+    if (new RegExp(`^(const\\s+)?${cls}\\s*\\(`).test(c))
+        return true; // unnamed constructor
+    if (new RegExp(`^factory\\s+${cls}\\.fromJson\\b`).test(c))
+        return true;
+    if (new RegExp(`^const\\s+factory\\s+${cls}\\s*\\(`).test(c))
+        return true; // freezed
+    if (/^(Map<String,\s*dynamic>|Map<String,\s*Object\?>)\s+toJson\s*\(/.test(c))
+        return true;
+    // A plain field: `final Type name;` (no initializer, no parentheses).
+    if (/^(final\s+|late\s+final\s+|late\s+)?[\w<>?, ]+\s+\w+\s*;$/.test(c.replace(/\s+/g, ' ')))
+        return true;
+    return false;
+}
+function fieldNames(members, cls) {
+    return new Set(members.filter((m) => isGenerated(m, cls) && /;\s*$/.test(m.code) && !/\(/.test(m.code)).map((m) => m.name));
+}
+export function mergeDart(oldText, newText) {
+    const report = { kept: new Map(), mentionsRemoved: new Map() };
+    const oldBlocks = classBlocks(oldText, maskCode(oldText, 'dart'));
+    let text = newText;
+    // From the last class down, so earlier offsets stay valid.
+    const newBlocks = [...classBlocks(text, maskCode(text, 'dart')).entries()].sort((a, b) => b[1].open - a[1].open);
+    for (const [cls, nb] of newBlocks) {
+        const ob = oldBlocks.get(cls);
+        if (!ob)
+            continue;
+        // freezed: @Default(...) values on factory parameters are yours; keep them.
+        const oldBody = oldText.slice(ob.open + 1, ob.close);
+        if (/\bconst\s+factory\b/.test(oldBody)) {
+            let body = text.slice(nb.open + 1, nb.close);
+            for (const d of oldBody.matchAll(/@Default\(((?:[^()]|\([^()]*\))*)\)\s+(?:required\s+)?[\w<>?, ]+?\s+(\w+)\s*[,)}]/g)) {
+                body = body.replace(new RegExp(`\\brequired\\s+([\\w<>, ]+\\s+${d[2]}\\s*,)`), `@Default(${d[1]}) $1`);
+            }
+            text = text.slice(0, nb.open + 1) + body + text.slice(nb.close);
+            nb.close = nb.open + 1 + body.length;
+        }
+        const oldMembers = splitDartMembers(oldText.slice(ob.open + 1, ob.close));
+        const newMembers = splitDartMembers(text.slice(nb.open + 1, nb.close));
+        const newNames = new Set(newMembers.map((m) => m.name));
+        const keep = oldMembers.filter((m) => !isGenerated(m, cls) && !newNames.has(m.name));
+        if (!keep.length)
+            continue;
+        const removed = [...fieldNames(oldMembers, cls)].filter((f) => !fieldNames(newMembers, cls).has(f));
+        const mentions = keep
+            .map((m) => ({ member: m.name, fields: removed.filter((f) => new RegExp(`\\b${f}\\b`).test(m.code)) }))
+            .filter((x) => x.fields.length);
+        if (mentions.length)
+            report.mentionsRemoved.set(cls, mentions);
+        report.kept.set(cls, keep.map((m) => m.name));
+        const before = text.slice(0, nb.close).replace(/\s*$/, '');
+        const block = keep.map((m) => m.text.replace(/^\n+/, '').replace(/\s+$/, '')).join('\n\n');
+        text = `${before}\n\n${block}\n${text.slice(nb.close)}`;
+    }
+    return { text, report };
+}
+/** TypeScript: comments above interface fields come back after regeneration. */
+export function mergeTsDocs(oldText, newText) {
+    const fieldRe = /^([ \t]*)(?:readonly\s+)?(['"]?[\w$-]+['"]?)\??\s*:/;
+    const docs = new Map();
+    const oldLines = oldText.split('\n');
+    for (let i = 0; i < oldLines.length; i++) {
+        const m = fieldRe.exec(oldLines[i]);
+        if (!m)
+            continue;
+        const doc = [];
+        let j = i - 1;
+        while (j >= 0 && /^\s*(\/\/|\/\*\*|\*|\*\/)/.test(oldLines[j]))
+            doc.unshift(oldLines[j--].trim());
+        if (doc.length)
+            docs.set(m[2], doc);
+    }
+    if (!docs.size)
+        return newText;
+    const out = [];
+    for (const line of newText.split('\n')) {
+        const m = fieldRe.exec(line);
+        const prev = out[out.length - 1] ?? '';
+        if (m && docs.has(m[2]) && !/^\s*(\/\/|\*|\/\*\*)/.test(prev)) {
+            for (const d of docs.get(m[2]))
+                out.push(`${m[1]}${d.startsWith('*') ? ' ' : ''}${d}`);
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}

package/dist/core/proc.js

@@ -0,0 +1,23 @@
+// Runs a project tool (flutter, npx, gradle, dart, the formatter...). On Windows
+// most of these are .cmd or .bat files, which only start through cmd.exe, and
+// cmd.exe splits on spaces: so there the command line is built here with every
+// argument quoted (paths like "C:\Users\Jo Doe\app" survive), instead of
+// letting Node join the arguments unquoted. An absolute path to an .exe (node
+// itself) runs directly, without a shell.
+import { spawnSync } from 'node:child_process';
+/** Quotes one argument for cmd.exe + the C runtime's argument parser. */
+export function winQuote(arg) {
+    if (arg !== '' && !/[\s"&|<>^()%!,;=]/.test(arg))
+        return arg;
+    return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+}
+export function runTool(cmd, args, opts = {}) {
+    const options = { ...opts, encoding: 'utf8' };
+    if (process.platform !== 'win32' || /^[a-zA-Z]:[\\/].*\.exe$/i.test(cmd))
+        return spawnSync(cmd, args, options);
+    return spawnSync([cmd, ...args].map(winQuote).join(' '), { ...options, shell: true });
+}
+/** True when a runTool result means the program is not installed (ENOENT, or cmd.exe's "not recognized"). */
+export function toolMissing(r) {
+    return r.error?.code === 'ENOENT' || (process.platform === 'win32' && r.status !== 0 && /is not recognized as an internal or external command/i.test(r.stderr ?? ''));
+}

package/dist/core/safe.js

@@ -0,0 +1,75 @@
+// Guards between untrusted input (cURL, HAR, OpenAPI, JSON samples, flags)
+// and generated source code. Every value that ends up inside a string
+// literal, a comment or a URL in generated code goes through one of these.
+//
+// Two layers: inputs are narrowed to safe characters where the meaning
+// allows it (URL paths are percent-encoded, hosts are checked), and string
+// literals are escaped for the target language anyway, so neither layer has
+// to be perfect on its own.
+import { ToolError } from "./types.js";
+/** Characters kept as they are in a URL path segment; everything else is percent-encoded. */
+const PATH_SAFE = /[A-Za-z0-9\-._~!&+,;=:@]/;
+/** Percent-encodes a decoded path segment so it holds no quote, backtick, $, \, *, braces or spaces. */
+export function encodePathSegment(seg) {
+    let out = '';
+    for (const ch of seg)
+        out += PATH_SAFE.test(ch) ? ch : [...Buffer.from(ch, 'utf8')].map((b) => `%${b.toString(16).toUpperCase().padStart(2, '0')}`).join('');
+    return out;
+}
+/** A host as URLs allow it, narrowed to what DNS names and IP addresses use. */
+const HOST = /^(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$|^\[[0-9A-Fa-f:.]+\]$/;
+/** Throws unless the URL's host is a plain DNS name or IP address (no quotes, backticks, $ or braces). */
+export function checkHost(url, what = 'The URL') {
+    if (!HOST.test(url.hostname))
+        throw new ToolError('bad_url', `${what} has a host codz will not write into code: "${url.hostname.slice(0, 80)}".`, 'Use a normal host name such as api.example.com.');
+}
+/** A base URL that is safe to write into generated code and config files: http(s), plain host, optional port and plain path. */
+const BASE_URL = /^https?:\/\/[^\s/?#]+(?::\d{1,5})?(?:\/[A-Za-z0-9\-._~!&+,;=:@%/]*)?$/;
+/** Returns the base URL without a trailing slash, or throws a clear error. */
+export function checkBaseUrl(value) {
+    const v = value.trim();
+    let u = null;
+    try {
+        u = new URL(v);
+    }
+    catch {
+        u = null;
+    }
+    if (!u || !BASE_URL.test(v) || (u.protocol !== 'https:' && u.protocol !== 'http:') || u.username || u.password) {
+        throw new ToolError('bad_url', `"${v.slice(0, 120)}" is not a base URL codz can use.`, 'Use something like https://api.example.com or https://api.example.com/v1 (no quotes, spaces, query or credentials).');
+    }
+    checkHost(u, 'The base URL');
+    return v.replace(/\/+$/, '');
+}
+/** Same check as checkBaseUrl, as an interactive prompt validator (null = fine). */
+export function baseUrlProblem(value) {
+    if (value === '')
+        return null;
+    try {
+        checkBaseUrl(value);
+        return null;
+    }
+    catch (e) {
+        return e instanceof ToolError ? `${e.message} ${e.hint ?? ''}`.trim() : 'Not a valid URL.';
+    }
+}
+/** A JavaScript/TypeScript string literal in the given quote (' " or `). */
+export function jsString(s, q) {
+    let body = s.replace(/\\/g, '\\\\').replace(/\r/g, '\\r').replace(/\n/g, '\\n').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    body = body.split(q).join(`\\${q}`);
+    if (q === '`')
+        body = body.replace(/\$\{/g, '\\${');
+    return `${q}${body}${q}`;
+}
+/** The inside of a JavaScript template literal (no backticks around it): escapes \, ` and ${. */
+export function jsTemplateText(s) {
+    return s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+/** A Kotlin string literal in double quotes: escapes \, ", $ and line breaks. */
+export function ktString(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/\r/g, '\\r').replace(/\n/g, '\\n')}"`;
+}
+/** Text that is safe inside a block or doc comment in TS, Dart and Kotlin: no comment end and one line. */
+export function commentText(s) {
+    return s.replace(/\*\//g, '*\u200b/').replace(/[\r\n]+/g, ' ');
+}

package/dist/core/templates.js

@@ -0,0 +1,100 @@
+// Custom templates: a project can change how generated code looks by keeping
+// template files in codz/templates/ (templatesFolder in the config).
+//
+// A template is the text to write, with {{placeholders}}. {{default}} is what
+// codz would have written, so a template can wrap it (add a header, a log
+// line, a decorator) or replace it using the other placeholders. Anything a
+// template changes must still look like code codz can read back (an
+// exported function, a class method), or later commands will not find it.
+import { join } from 'node:path';
+import { loadConfig } from "./config.js";
+import { readText } from "./fsutil.js";
+export const DEFAULT_TEMPLATES_FOLDER = 'codz/templates';
+export const TEMPLATES = [
+    {
+        id: 'file-header.ts',
+        about: 'text at the top of every TypeScript file codz creates',
+        vars: { file: 'path of the new file' },
+        example: '// Generated by codz. Edit freely.\n',
+    },
+    {
+        id: 'file-header.dart',
+        about: 'text at the top of every Dart file codz creates',
+        vars: { file: 'path of the new file' },
+        example: '// Generated by codz. Edit freely.\n',
+    },
+    {
+        id: 'api-function.ts',
+        about: 'a Next.js API function',
+        vars: { default: "codz's function", name: 'function name', method: 'HTTP method', path: 'API path', params: 'parameter list', returnType: 'resolved type' },
+        example: '{{default}}\n',
+    },
+    {
+        id: 'api-method.dart',
+        about: 'a Flutter repository method or Retrofit method',
+        vars: { default: "codz's method", name: 'method name', method: 'HTTP method', path: 'API path', returnType: 'resolved type' },
+        example: '{{default}}\n',
+    },
+    {
+        id: 'model.ts',
+        about: 'a TypeScript interface for API data',
+        vars: { default: "codz's interface", name: 'interface name' },
+        example: '{{default}}\n',
+    },
+    {
+        id: 'model.dart',
+        about: 'a Dart model class (manual, json_serializable or freezed)',
+        vars: { default: "codz's class, with its imports and part lines", name: 'class name' },
+        example: '{{default}}\n',
+    },
+];
+export function templatesFolder(root) {
+    return loadConfig(root).conventions.templatesFolder || DEFAULT_TEMPLATES_FOLDER;
+}
+const cache = new Map();
+/** The project's template for `id`, or null when it has none. */
+export function loadTemplate(root, id) {
+    const file = join(root, templatesFolder(root), `${id}.tmpl`);
+    if (!cache.has(file))
+        cache.set(file, readText(file));
+    return cache.get(file);
+}
+/** For tests: forget templates read earlier. */
+export function clearTemplateCache() {
+    cache.clear();
+}
+/** Fills {{name}} placeholders; unknown ones are left as written and reported. */
+export function render(template, vars) {
+    const unknown = [];
+    const text = template.replace(/\{\{\s*(\w+)\s*\}\}/g, (all, k) => {
+        if (k in vars)
+            return vars[k];
+        unknown.push(k);
+        return all;
+    });
+    return { text, unknown };
+}
+/**
+ * Runs `rendered` (codz's own output) through the project's template, if any.
+ * Trailing newlines follow codz's output so blocks still join cleanly.
+ */
+export function applyTemplate(root, id, rendered, vars, warnings) {
+    const t = loadTemplate(root, id);
+    if (t === null)
+        return rendered;
+    const r = render(t, { ...vars, default: rendered });
+    if (r.unknown.length && warnings)
+        warnings.push(`Template ${id}.tmpl uses unknown placeholders: ${[...new Set(r.unknown)].map((u) => `{{${u}}}`).join(', ')}. Known: ${Object.keys(TEMPLATES.find((x) => x.id === id)?.vars ?? {}).map((v) => `{{${v}}}`).join(', ')}.`);
+    return r.text.replace(/\n+$/, '') + (rendered.match(/\n+$/)?.[0] ?? '');
+}
+/** The header template for a new file, by extension. */
+export function fileHeader(root, path) {
+    const id = /\.(tsx?|jsx?|mjs)$/.test(path) ? 'file-header.ts' : /\.dart$/.test(path) ? 'file-header.dart' : null;
+    if (!id)
+        return '';
+    const t = loadTemplate(root, id);
+    if (t === null)
+        return '';
+    const text = render(t, { file: path }).text;
+    return text.endsWith('\n') ? text : `${text}\n`;
+}

package/dist/core/tsAst.js

@@ -0,0 +1,112 @@
+// TypeScript syntax trees for exact rename/remove/usage analysis, using the TypeScript compiler the
+// project already has (node_modules/typescript). codz itself has no runtime
+// dependencies, so when the project has no TypeScript (or CODZ_NO_AST=1),
+// callers fall back to the text scanner.
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { exists } from "./fsutil.js";
+const cache = new Map();
+/** The project's TypeScript module, or codz's own in development, or null. */
+export function loadTypeScript(root) {
+    if (process.env.CODZ_NO_AST === '1')
+        return null;
+    if (cache.has(root))
+        return cache.get(root);
+    let ts = null;
+    for (const base of [join(root, 'package.json'), import.meta.url]) {
+        try {
+            if (base.endsWith('package.json') && !exists(join(root, 'node_modules', 'typescript')))
+                continue;
+            const mod = createRequire(base)('typescript');
+            if (mod?.createSourceFile) {
+                ts = mod;
+                break;
+            }
+        }
+        catch {
+            // Not installed there.
+        }
+    }
+    cache.set(root, ts);
+    return ts;
+}
+function parse(ts, file, text) {
+    const kind = /\.tsx$/.test(file) ? ts.ScriptKind.TSX : /\.jsx?$|\.mjs$/.test(file) ? ts.ScriptKind.JSX : ts.ScriptKind.TS;
+    return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+}
+/**
+ * Every place an identifier refers to the module-level binding `name`: calls,
+ * references, import and export specifiers, and `ns.name` through a namespace
+ * import. Skips property names on other objects, object keys, strings,
+ * comments, and code where a local variable or parameter shadows the name.
+ */
+export function tsIdentifierUses(ts, file, text, name, opts = {}) {
+    const sf = parse(ts, file, text);
+    const namespaces = new Set();
+    for (const st of sf.statements) {
+        if (ts.isImportDeclaration(st) && st.importClause?.namedBindings && ts.isNamespaceImport(st.importClause.namedBindings))
+            namespaces.add(st.importClause.namedBindings.name.text);
+    }
+    const out = [];
+    // Does this function or block declare its own `name` (a parameter, or a
+    // variable, function or class directly inside it)? Nested blocks and
+    // functions are their own scopes and are checked when the walk gets there.
+    const declares = (node) => {
+        const items = [];
+        if (ts.isFunctionLike(node)) {
+            items.push(...(node.parameters ?? []));
+            if (node.body && ts.isBlock(node.body))
+                items.push(...node.body.statements);
+        }
+        else if (ts.isBlock(node))
+            items.push(...node.statements);
+        let found = false;
+        const visit = (n) => {
+            if (found)
+                return;
+            if ((ts.isParameter(n) || ts.isVariableDeclaration(n) || ts.isBindingElement(n)) && n.name && ts.isIdentifier(n.name) && n.name.text === name)
+                found = true;
+            else if (ts.isBlock(n) || ts.isFunctionLike(n) || ts.isClassLike(n)) {
+                if ((ts.isFunctionDeclaration(n) || ts.isClassDeclaration(n)) && n.name?.text === name)
+                    found = true;
+                return;
+            }
+            else
+                ts.forEachChild(n, visit);
+        };
+        items.forEach(visit);
+        return found;
+    };
+    const walk = (n, shadowed) => {
+        const scopeShadows = !shadowed && (ts.isFunctionLike(n) || ts.isBlock(n)) && n !== sf && declares(n);
+        const sh = shadowed || scopeShadows;
+        if (ts.isIdentifier(n) && n.text === name) {
+            const p = n.parent;
+            const at = n.getStart(sf);
+            const line = sf.getLineAndCharacterOfPosition(at).line + 1;
+            if (opts.declStart !== undefined && at === opts.declStart)
+                return;
+            if (ts.isImportSpecifier(p) || ts.isImportClause(p))
+                out.push({ index: at, line, kind: 'import' });
+            else if (ts.isExportSpecifier(p))
+                out.push({ index: at, line, kind: 'export' });
+            else if (ts.isPropertyAccessExpression(p) && p.name === n) {
+                if (ts.isIdentifier(p.expression) && namespaces.has(p.expression.text) && !sh)
+                    out.push({ index: at, line, kind: ts.isCallExpression(p.parent) ? 'call' : 'reference' });
+            }
+            else if ((ts.isPropertyAssignment(p) || ts.isPropertySignature(p) || ts.isMethodDeclaration(p) || ts.isPropertyDeclaration(p) || ts.isMethodSignature(p)) && p.name === n) {
+                // An object key or class member with the same name: not a use.
+            }
+            else if (ts.isShorthandPropertyAssignment(p) && !sh)
+                out.push({ index: at, line, kind: 'reference' });
+            else if ((ts.isParameter(p) || ts.isVariableDeclaration(p) || ts.isFunctionDeclaration(p)) && p.name === n) {
+                // A declaration (the endpoint itself, or a local that shadows it).
+            }
+            else if (!sh)
+                out.push({ index: at, line, kind: ts.isCallExpression(p) && p.expression === n ? 'call' : 'reference' });
+        }
+        ts.forEachChild(n, (c) => walk(c, sh));
+    };
+    walk(sf, false);
+    return out;
+}

package/dist/core/types.js

@@ -0,0 +1,12 @@
+// Shared types: the framework-neutral project map, the universal endpoint
+// object that skills build, change sets, and the adapter interface.
+export const MAP_SCHEMA_VERSION = 1;
+export class ToolError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+    }
+}