arcscope 0.0.1

package/dist/knowledge/vocab-loader.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+// Load and validate .arcscope/vocab.yaml. The file is hand-authored and committed
+// (the repo's declared knowledge), so we fail loud on a malformed shape rather than
+// silently dropping concepts. Returns an empty vocabulary if the file is absent.
+export function loadVocabulary(vocabPath) {
+    if (!existsSync(vocabPath))
+        return { concepts: [] };
+    let raw;
+    try {
+        raw = yaml.load(readFileSync(vocabPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`vocab.yaml is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const conceptsObj = isRecord(raw) && isRecord(raw['concepts']) ? raw['concepts'] : {};
+    const concepts = [];
+    for (const [id, value] of Object.entries(conceptsObj)) {
+        concepts.push(parseConcept(id, value));
+    }
+    return { concepts };
+}
+function parseConcept(id, value) {
+    if (!isRecord(value))
+        throw new Error(`concept "${id}" must be a mapping`);
+    const locators = value['locators'];
+    const stages = value['stages'];
+    const concept = {
+        id,
+        title: typeof value['title'] === 'string' ? value['title'] : id,
+        description: typeof value['description'] === 'string' ? value['description'] : undefined,
+        note: typeof value['note'] === 'string' ? value['note'] : undefined,
+    };
+    if (Array.isArray(stages)) {
+        concept.stages = stages.map((s, i) => parseStage(id, i, s));
+    }
+    else if (Array.isArray(locators)) {
+        concept.locators = locators.map((l, i) => parseLocator(`${id}.locators[${i}]`, l));
+    }
+    else {
+        throw new Error(`concept "${id}" must have a "locators" or "stages" list`);
+    }
+    return concept;
+}
+function parseStage(conceptId, i, value) {
+    if (!isRecord(value) || typeof value['title'] !== 'string') {
+        throw new Error(`concept "${conceptId}" stage ${i} must be a mapping with a "title"`);
+    }
+    return { ...parseLocator(`${conceptId}.stages[${i}]`, value), title: value['title'] };
+}
+function parseLocator(where, value) {
+    if (!isRecord(value))
+        throw new Error(`${where} must be a mapping`);
+    const inGlob = typeof value['in'] === 'string' ? value['in'] : undefined;
+    if (value['kind'] === 'symbol') {
+        if (typeof value['query'] !== 'string')
+            throw new Error(`${where} (symbol) needs a "query" string`);
+        return { kind: 'symbol', query: value['query'], in: inGlob };
+    }
+    if (value['kind'] === 'path') {
+        if (typeof value['glob'] !== 'string')
+            throw new Error(`${where} (path) needs a "glob" string`);
+        return { kind: 'path', glob: value['glob'], in: inGlob };
+    }
+    throw new Error(`${where} has unknown kind ${JSON.stringify(value['kind'])} (v1 supports: symbol, path)`);
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/log.js

@@ -0,0 +1,9 @@
+// stderr-ONLY logging. This is the single chokepoint that enforces stdio hygiene:
+// arcscope speaks JSON-RPC on stdout, and a stray write to stdout corrupts that
+// stream and silently hangs the server. Never use console.log anywhere; log here.
+export function log(...args) {
+    console.error('[arcscope]', ...args);
+}
+export function logError(...args) {
+    console.error('[arcscope:error]', ...args);
+}

package/dist/server/serve.js

@@ -0,0 +1,179 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { GrammarRegistry } from '../engine/grammar-registry.js';
+import { IndexStore } from '../engine/index-store.js';
+import { InvocationCounter } from '../adoption/counter.js';
+import { runFindDef, findDefInputShape } from '../tools/find-def.js';
+import { runFindRefs, findRefsInputShape } from '../tools/find-refs.js';
+import { runDepGraph, depGraphInputShape } from '../tools/dep-graph.js';
+import { runArchList } from '../tools/arch-list.js';
+import { runArchQuery, archQueryInputShape } from '../tools/arch-query.js';
+import { log, logError } from '../log.js';
+// Read from package.json (shipped in the tarball) so it never drifts from the
+// published version.
+const VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+// Server-level instructions are surfaced by the client (Claude Code) at session
+// start and are the highest-leverage adoption lever: they tell the agent WHEN to
+// reach for arcscope instead of grep. Kept concise (clients truncate ~2KB).
+const INSTRUCTIONS = [
+    'arcscope navigates this codebase by parsing it with tree-sitter — fully local, no network.',
+    'Prefer it over grep/Glob for structural questions about where code lives.',
+    '',
+    'Use find_def to locate where a named symbol is defined (function, class, method, interface,',
+    'type, enum, or exported constant). It returns the exact definition site and signature, and',
+    'skips the comments, strings, and unrelated same-named matches that text search turns up.',
+    "When you need \"where is X defined?\", call find_def with the symbol name instead of searching text.",
+    '',
+    'Use find_refs to find who references a symbol. It resolves tsconfig aliases and barrel',
+    're-exports, so it finds callers grep misses and excludes same-named symbols in unrelated files —',
+    'much more precise than grepping a name. Prefer it for "what uses X?" / "who calls X?".',
+    '',
+    'Use dep_graph to see structure: the most depended-on files (hubs) with no focus, or a file\'s',
+    'neighborhood (what it imports / what imports it) with a focus. Prefer it over reading imports by hand.',
+    '',
+    "Use arch_list to learn this repo's named architecture concepts (its committed vocabulary), and arch_query",
+    'to resolve one live to its current code locations. These answer concept-level questions ("the repository',
+    'tokens", "the action pipeline") that grep and docs can\'t — recomputed every call, so they never go stale.',
+    '',
+    "Every result is labeled with a precision tier so you can calibrate trust (currently",
+    "'tree-sitter': structural and high-signal, but not compiler-exact).",
+].join('\n');
+const ARCH_LIST_DESCRIPTION = [
+    "List this repo's declared architecture concepts — named, repo-committed ideas (e.g. \"the repository tokens\",",
+    '"the editor state pipeline", "the plugin registry") bound to live code locators. Use at the START of working',
+    'in an unfamiliar codebase to learn its vocabulary, or when the user names an architectural concept. Each is',
+    'answered live against current code (never stale prose).',
+].join(' ');
+const ARCH_QUERY_DESCRIPTION = [
+    'Resolve one named architecture concept to its live code locations. Use when you need to understand or change a',
+    'declared concept (from arch_list) — it recomputes the locator against the current tree and returns the exact',
+    'files/symbols (a staged concept comes back as an ordered pipeline). More reliable than reading prose docs,',
+    'which silently rot; this is recomputed every call and flags drift.',
+].join(' ');
+const DEP_GRAPH_DESCRIPTION = [
+    'Show the module/file dependency graph from real import edges (resolving aliases + barrels).',
+    'Use to understand structure: with no focus it returns the most depended-on files (hubs) and a',
+    'module summary; with a focus file it returns that file\'s neighborhood — what it imports and what',
+    'imports it; with cycles:true it finds circular dependencies (files that import each other).',
+    'Optionally a directory prefix focus, or a neighborhood depth (1-2). Token-bounded.',
+].join(' ');
+const FIND_REFS_DESCRIPTION = [
+    'Find where a symbol is referenced (its callers/consumers), following tsconfig path aliases and',
+    'barrel re-exports. Use when you need who uses a function, class, method, interface, type, or',
+    'constant — e.g. "what calls ActionRouterService?". More precise than text search: it resolves',
+    'which files actually import the symbol, so it excludes same-named symbols in unrelated files and',
+    'includes references reached through barrels. Each reference carries its kind (call/new/type/...)',
+    'and the definition it resolves to.',
+].join(' ');
+const FIND_DEF_DESCRIPTION = [
+    'Find where a symbol is defined and show its signature.',
+    'Use when you need the definition site of a named function, class, method, interface, type,',
+    "enum, or exported constant — e.g. \"where is GraphReducer defined?\".",
+    'More precise than text search: it parses the code, so it skips comments, strings, and unrelated',
+    'same-named matches. Returns each definition as file:line, kind, and header signature, with a',
+    'precision tier. If no exact match exists, it suggests symbols with similar names — so you can',
+    "call it even when you're unsure of the precise name. Optionally scope to part of the repo with a path glob.",
+].join(' ');
+export async function serve(root) {
+    const registry = new GrammarRegistry();
+    const store = new IndexStore(root, registry);
+    const counter = new InvocationCounter(join(root, '.arcscope', 'usage.jsonl'));
+    const stats = await store.sync();
+    log(`indexed ${stats.fileCount} files, ${stats.symbolCount} symbols in ${stats.elapsedMs}ms (root: ${root})`);
+    const server = new McpServer({ name: 'arcscope', version: VERSION }, { instructions: INSTRUCTIONS });
+    server.registerTool('find_def', {
+        title: 'Find symbol definition',
+        description: FIND_DEF_DESCRIPTION,
+        inputSchema: findDefInputShape,
+    }, async (args) => {
+        void counter.record('find_def', args);
+        try {
+            const { text } = await runFindDef(store, args);
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            logError('find_def failed:', err);
+            return {
+                content: [{ type: 'text', text: `find_def error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('find_refs', {
+        title: 'Find symbol references',
+        description: FIND_REFS_DESCRIPTION,
+        inputSchema: findRefsInputShape,
+    }, async (args) => {
+        void counter.record('find_refs', args);
+        try {
+            const { text } = await runFindRefs(store, registry, root, args);
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            logError('find_refs failed:', err);
+            return {
+                content: [{ type: 'text', text: `find_refs error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('dep_graph', {
+        title: 'Module dependency graph',
+        description: DEP_GRAPH_DESCRIPTION,
+        inputSchema: depGraphInputShape,
+    }, async (args) => {
+        void counter.record('dep_graph', args);
+        try {
+            const { text } = await runDepGraph(store, root, args);
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            logError('dep_graph failed:', err);
+            return {
+                content: [{ type: 'text', text: `dep_graph error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('arch_list', { title: 'List architecture concepts', description: ARCH_LIST_DESCRIPTION }, async () => {
+        void counter.record('arch_list', {});
+        try {
+            const { text } = await runArchList(store, root);
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            logError('arch_list failed:', err);
+            return {
+                content: [{ type: 'text', text: `arch_list error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('arch_query', { title: 'Resolve an architecture concept', description: ARCH_QUERY_DESCRIPTION, inputSchema: archQueryInputShape }, async (args) => {
+        void counter.record('arch_query', args);
+        try {
+            const { text } = await runArchQuery(store, root, args);
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            logError('arch_query failed:', err);
+            return {
+                content: [{ type: 'text', text: `arch_query error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log('serving on stdio');
+}

package/dist/tools/arch-list.js

@@ -0,0 +1,33 @@
+import { join } from 'node:path';
+import { loadVocabulary } from '../knowledge/vocab-loader.js';
+import { resolveConcept } from '../knowledge/resolver.js';
+import { computeAnchors, compareDrift, loadAnchorStore, baselineFor } from '../knowledge/drift.js';
+// List the repo's declared architecture concepts (progressive disclosure: names +
+// counts + freshness first). Resolved LIVE; read-only — never captures a baseline
+// (that's arch_query's job), so unqueried concepts show as "unverified".
+export async function runArchList(store, root) {
+    await store.sync();
+    const vocab = loadVocabulary(join(root, '.arcscope', 'vocab.yaml'));
+    if (vocab.concepts.length === 0) {
+        return {
+            conceptCount: 0,
+            text: 'No architecture vocabulary found. Add named concepts to .arcscope/vocab.yaml (committed) to make this repo self-describing.',
+        };
+    }
+    const anchorStore = loadAnchorStore(root);
+    const lines = vocab.concepts.map((c) => {
+        const resolved = resolveConcept(store, c);
+        const baseline = baselineFor(anchorStore, c.id);
+        const freshness = baseline ? compareDrift(computeAnchors(root, resolved), baseline).status : 'unverified';
+        return `  ${c.id}${c.stages ? ' (staged)' : ''} — ${c.title} · ${resolved.length} location${resolved.length === 1 ? '' : 's'} [${freshness}]`;
+    });
+    return {
+        conceptCount: vocab.concepts.length,
+        text: [
+            `${vocab.concepts.length} architecture concept${vocab.concepts.length === 1 ? '' : 's'} (answered live against current code):`,
+            ...lines,
+            '',
+            'Use arch_query <id> to resolve one concept to its live locations (and capture/check its drift baseline).',
+        ].join('\n'),
+    };
+}

package/dist/tools/arch-query.js

@@ -0,0 +1,81 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { loadVocabulary } from '../knowledge/vocab-loader.js';
+import { resolveConcept } from '../knowledge/resolver.js';
+import { computeAnchors, compareDrift, loadAnchorStore, baselineFor, captureBaseline } from '../knowledge/drift.js';
+export const archQueryInputShape = {
+    concept: z.string().min(1).describe("Concept id from arch_list, e.g. 'repository-tokens' or 'editor-state-flow'."),
+    reaccept: z
+        .boolean()
+        .optional()
+        .describe('Re-snapshot the drift baseline to the current resolution (use after a legitimate change that the concept should now treat as correct).'),
+};
+// Resolve one named concept LIVE against the current tree — never cached prose.
+// (Drift detection is layered on in Slice 2.)
+export async function runArchQuery(store, root, args) {
+    await store.sync();
+    const vocab = loadVocabulary(join(root, '.arcscope', 'vocab.yaml'));
+    const concept = vocab.concepts.find((c) => c.id === args.concept);
+    if (!concept) {
+        const known = vocab.concepts.length
+            ? ` Known concepts: ${vocab.concepts.map((c) => c.id).join(', ')}.`
+            : ' (.arcscope/vocab.yaml is missing or empty.)';
+        return { resolved: [], freshness: 'unknown', text: `No concept "${args.concept}" in the vocabulary.${known}` };
+    }
+    const resolved = resolveConcept(store, concept);
+    // Drift: capture a baseline on first query (or --reaccept), else compare.
+    const current = computeAnchors(root, resolved);
+    const baseline = baselineFor(loadAnchorStore(root), concept.id);
+    let freshness;
+    let drift;
+    if (!baseline || args.reaccept) {
+        captureBaseline(root, concept.id, current, new Date().toISOString());
+        freshness = baseline ? 'fresh (baseline re-captured)' : 'fresh (baseline captured)';
+    }
+    else {
+        drift = compareDrift(current, baseline);
+        freshness = drift.status === 'drifted' ? 'DRIFTED' : 'fresh';
+    }
+    return { resolved, freshness, drift, text: formatConcept(concept, resolved, freshness, drift) };
+}
+export function formatConcept(concept, resolved, freshness, drift) {
+    const tag = freshness ? `, ${freshness}` : ', answered live';
+    const head = `Concept \`${concept.id}\` — ${concept.title} (${resolved.length} location${resolved.length === 1 ? '' : 's'}${tag}):`;
+    const body = [];
+    if (concept.description)
+        body.push(`  ${concept.description}`);
+    if (concept.stages) {
+        for (const stage of concept.stages) {
+            body.push(`  ▸ ${stage.title}`);
+            const locs = resolved.filter((r) => r.stage === stage.title);
+            if (locs.length === 0)
+                body.push('      (no match — possible drift)');
+            for (const r of locs)
+                body.push(`      ${formatLoc(r)}`);
+        }
+    }
+    else {
+        if (resolved.length === 0)
+            body.push('  (nothing resolved — the locators may need updating, or the concept drifted)');
+        for (const r of resolved)
+            body.push(`  ${formatLoc(r)}`);
+    }
+    if (concept.note)
+        body.push(`  note: ${concept.note}`);
+    if (drift && drift.status === 'drifted') {
+        body.push('', `  ⚠ DRIFT vs baseline: ${drift.added.length} added, ${drift.removed.length} removed, ${drift.changed.length} changed.`);
+        for (const k of drift.added.slice(0, 5))
+            body.push(`    + ${k}`);
+        for (const k of drift.removed.slice(0, 5))
+            body.push(`    - ${k}`);
+        for (const k of drift.changed.slice(0, 5))
+            body.push(`    ~ ${k} (definition changed)`);
+        body.push('  If this change is correct, re-run arch_query with reaccept:true to update the baseline.');
+    }
+    return [head, ...body].join('\n');
+}
+function formatLoc(r) {
+    if (r.via === 'path')
+        return `${r.file}  [file]`;
+    return `${r.file}:${r.line}  [${r.kind}]  ${r.signature ?? ''}`.trimEnd();
+}

package/dist/tools/find-def.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+const FUZZY_MIN_LENGTH = 3;
+// Zod raw shape for the find_def tool input (registerTool accepts a raw shape).
+// The .describe() text is part of the adoption surface the agent reads.
+export const findDefInputShape = {
+    symbol: z
+        .string()
+        .min(1)
+        .describe("Exact symbol name to locate (case-sensitive), e.g. 'GraphReducer', 'useAuth', 'IThingRepository'."),
+    pathGlob: z
+        .string()
+        .optional()
+        .describe("Optional path glob to scope results, e.g. 'libs/features/**' or 'src/**/*.ts'."),
+};
+// Tool logic, independent of the MCP transport so it can be unit-tested directly.
+// Re-syncs the index (lazy re-index) so results always reflect the current tree.
+// Exact match is the precise default; on zero hits it falls back to close-name
+// suggestions so the agent doesn't have to guess the exact symbol name.
+export async function runFindDef(store, args) {
+    await store.sync();
+    const records = store.find(args.symbol, args.pathGlob);
+    if (records.length > 0) {
+        return { records, suggestions: [], text: formatExact(args.symbol, args.pathGlob, records) };
+    }
+    const suggestions = args.symbol.length >= FUZZY_MIN_LENGTH ? store.findFuzzy(args.symbol, args.pathGlob) : [];
+    return { records: [], suggestions, text: formatMiss(args.symbol, args.pathGlob, suggestions, store.fileCount) };
+}
+function formatExact(symbol, pathGlob, records) {
+    const scope = pathGlob ? ` within \`${pathGlob}\`` : '';
+    const head = `${records.length} definition${records.length === 1 ? '' : 's'} of \`${symbol}\`${scope} (precision: tree-sitter):`;
+    // The symbol is in the header, so exact lines omit it.
+    const lines = records.map((r) => `  ${r.file}:${r.line}  [${r.kind}]  ${r.signature}`);
+    return [head, ...lines].join('\n');
+}
+function formatMiss(symbol, pathGlob, suggestions, fileCount) {
+    const scope = pathGlob ? ` within \`${pathGlob}\`` : '';
+    if (suggestions.length === 0) {
+        return (`No definition of \`${symbol}\` found${scope} (searched ${fileCount} files via tree-sitter). ` +
+            'It may be defined in a gitignored/untracked file, imported from a dependency, or spelled ' +
+            'differently — find_def matches names exactly and is case-sensitive.');
+    }
+    const head = `No exact definition of \`${symbol}\`${scope}, but ${suggestions.length} symbol${suggestions.length === 1 ? ' has' : 's have'} a similar name (matched by name; locations are exact):`;
+    // Suggestions are distinct names, so each line leads with the symbol.
+    const lines = suggestions.map((r) => `  ${r.symbol}  [${r.kind}]  ${r.file}:${r.line}  ${r.signature}`);
+    return [head, ...lines, 'Re-run find_def with one of these exact names for the full, precise result.'].join('\n');
+}

package/dist/tools/find-refs.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ImportGraph } from '../engine/import-graph.js';
+import { findOccurrences } from '../engine/ref-scan.js';
+import { matchGlob } from '../engine/glob.js';
+export const findRefsInputShape = {
+    symbol: z
+        .string()
+        .min(1)
+        .describe("Exact symbol name to find references to (case-sensitive), e.g. 'GraphReducer'."),
+    pathGlob: z
+        .string()
+        .optional()
+        .describe("Optional path glob to scope which referencing files are reported, e.g. 'apps/**'."),
+};
+// Who references a symbol — resolved through tsconfig aliases + barrel re-exports.
+// Uses the import graph to find which files actually import the symbol, then scans
+// only those files (+ the definition file) for usages. Same-named symbols in
+// files that don't import it are excluded — that's the precision win over grep.
+export async function runFindRefs(store, registry, root, args) {
+    await store.sync();
+    const defs = store.find(args.symbol);
+    if (defs.length === 0) {
+        return {
+            records: [],
+            text: `No definition of \`${args.symbol}\` found, so there is nothing to resolve references against. Try find_def first (it suggests similar names).`,
+        };
+    }
+    const graph = new ImportGraph(store, root);
+    const records = [];
+    let importerCount = 0;
+    const scanned = new Set();
+    for (const def of defs) {
+        const sites = [
+            { file: def.file, local: args.symbol }, // intra-file uses in the definition file
+            ...graph.importersOf(args.symbol, def.file),
+        ];
+        for (const site of sites) {
+            if (site.file !== def.file)
+                importerCount++;
+            if (scanned.has(site.file))
+                continue;
+            scanned.add(site.file);
+            let source;
+            try {
+                source = readFileSync(join(root, site.file), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            for (const occ of await findOccurrences(registry, site.file, source, site.local)) {
+                if (args.pathGlob && !matchGlob(occ.file, args.pathGlob))
+                    continue;
+                records.push({
+                    symbol: site.local,
+                    file: occ.file,
+                    line: occ.line,
+                    column: occ.column,
+                    snippet: occ.snippet,
+                    refKind: occ.refKind,
+                    resolved: true,
+                    resolvesTo: { file: def.file, line: def.line },
+                    precisionTier: 'tree-sitter',
+                });
+            }
+        }
+    }
+    records.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1));
+    const kinds = new Set(defs.map((d) => d.kind));
+    return { records, text: format(args.symbol, args.pathGlob, defs.length, importerCount, records, kinds) };
+}
+function format(symbol, pathGlob, defCount, importerCount, records, kinds) {
+    const scope = pathGlob ? ` within \`${pathGlob}\`` : '';
+    if (records.length === 0) {
+        // find_refs is import-resolution based, so a symbol that is never imported by
+        // name (a method/object-property invoked via member access, used only in its
+        // own file, or reached via namespace/default import) yields nothing. Say so.
+        const memberHint = kinds.has('method') ? ` Since \`${symbol}\` is (or includes) a method, it is invoked via member access (\`obj.${symbol}()\`) — find_refs its declaring class/interface, or grep \`.${symbol}\`.` : '';
+        return (`No import-resolved references to \`${symbol}\`${scope} (${defCount} definition${defCount === 1 ? '' : 's'}). find_refs follows imports, so it does not find a symbol referenced only via member access, used only within its own file, or reached through namespace/default imports.` +
+            memberHint);
+    }
+    const defNote = defCount > 1 ? ` (${defCount} definitions share this name; refs are split by the one they resolve to)` : '';
+    const head = `${records.length} reference${records.length === 1 ? '' : 's'} to \`${symbol}\`${scope}${defNote} — resolved through imports/barrels (precision: tree-sitter):`;
+    const lines = records.map((r) => `  ${r.file}:${r.line}  [${r.refKind}]  ${r.snippet}` + (r.resolvesTo ? `  -> ${r.resolvesTo.file}:${r.resolvesTo.line}` : ''));
+    const foot = `Resolved across ${importerCount} importing file${importerCount === 1 ? '' : 's'} + the definition; same-named symbols in files that don't import it are excluded.`;
+    return [head, ...lines, foot].join('\n');
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "arcscope",
+  "version": "0.0.1",
+  "description": "Fully-local, architecture-aware code-navigation MCP server. tree-sitter breadth + a repo-declared architecture vocabulary answered live.",
+  "type": "module",
+  "author": "Ilie Danila",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iliedanila/arcscope.git"
+  },
+  "homepage": "https://github.com/iliedanila/arcscope#readme",
+  "bugs": {
+    "url": "https://github.com/iliedanila/arcscope/issues"
+  },
+  "bin": {
+    "arcscope": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "shx rm -rf dist",
+    "build": "shx rm -rf dist && tsc -p tsconfig.build.json && shx cp -r vendor/grammars dist/grammars && shx chmod +x dist/index.js",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "vendor:grammars": "shx cp node_modules/web-tree-sitter/web-tree-sitter.wasm vendor/grammars/ && shx cp node_modules/tree-sitter-typescript/tree-sitter-typescript.wasm node_modules/tree-sitter-typescript/tree-sitter-tsx.wasm node_modules/tree-sitter-javascript/tree-sitter-javascript.wasm vendor/grammars/ && shx cp node_modules/tree-sitter-typescript/queries/tags.scm vendor/grammars/typescript-tags.scm && shx cp node_modules/tree-sitter-javascript/queries/tags.scm vendor/grammars/javascript-tags.scm"
+  },
+  "keywords": [
+    "mcp",
+    "tree-sitter",
+    "code-navigation",
+    "architecture",
+    "local"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "js-yaml": "^4.2.0",
+    "web-tree-sitter": "^0.26.9",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.0.0",
+    "shx": "^0.4.0",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-typescript": "^0.23.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.0"
+  }
+}