arcscope 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilie Danila
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# arcscope
+
+A fully-local MCP server that gives an AI coding agent three stacked views of an unfamiliar codebase — symbols, the module/dependency graph, and a repo-declared **architecture vocabulary** answered *live* against current code — so it stops re-deriving structure with grep every session.
+
+**Status:** design complete, pre-build. See the full spec: [`docs/arcscope-spec.html`](docs/arcscope-spec.html).
+
+The wedge: where existing tools keep project knowledge as static prose that silently rots, arcscope binds each named concept to an executable locator that is recomputed on every query — so drift is a signal, not a surprise.
+
+> Building with Claude Code? Start at [`CLAUDE.md`](CLAUDE.md).

package/dist/adoption/counter.js

@@ -0,0 +1,23 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { logError } from '../log.js';
+// Local-only invocation counter for the adoption gate. Appends one JSONL line per
+// tool call to .arcscope/usage.jsonl so the grep-vs-tool ratio can be inspected
+// during dogfooding. NEVER touches the network. Fire-and-forget: a failed write
+// is logged to stderr and swallowed — instrumentation must never break the tool.
+export class InvocationCounter {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    async record(tool, args) {
+        const line = JSON.stringify({ ts: new Date().toISOString(), tool, args }) + '\n';
+        try {
+            await mkdir(dirname(this.file), { recursive: true });
+            await appendFile(this.file, line, 'utf8');
+        }
+        catch (err) {
+            logError('usage counter write failed (non-fatal):', err);
+        }
+    }
+}

package/dist/engine/discover.js

@@ -0,0 +1,53 @@
+import { execFileSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+// Source extensions arcscope parses in P0 (TS/JS family). .d.ts is excluded
+// separately — declaration files hold no navigable definitions.
+const SOURCE_RE = /\.(?:[cm]?ts|tsx|[cm]?js|jsx)$/;
+const DECL_RE = /\.d\.[cm]?ts$/;
+// Directories the non-git fallback walk never descends into.
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'out', 'coverage', '.arcscope']);
+export function isSourceFile(name) {
+    return SOURCE_RE.test(name) && !DECL_RE.test(name);
+}
+// Returns absolute paths of source files under `root`.
+//
+// git-first: `git ls-files` (tracked + untracked-not-ignored) respects .gitignore
+// for free, which is the single biggest correctness/perf lever — on a real repo it
+// is the difference between ~1k real source files and ~18k including dist/ and
+// tool caches. Falls back to a directory walk when `root` is not a git repo.
+export function discoverFiles(root) {
+    return discoverViaGit(root) ?? walk(root, []);
+}
+function discoverViaGit(root) {
+    try {
+        const raw = execFileSync('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+        return raw
+            .split('\0')
+            .filter((rel) => rel.length > 0 && isSourceFile(rel))
+            .map((rel) => join(root, rel));
+    }
+    catch {
+        return null; // not a git repo / git unavailable -> walk
+    }
+}
+function walk(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            if (SKIP_DIRS.has(e.name) || e.name.startsWith('.'))
+                continue;
+            walk(join(dir, e.name), out);
+        }
+        else if (e.isFile() && isSourceFile(e.name)) {
+            out.push(join(dir, e.name));
+        }
+    }
+    return out;
+}

package/dist/engine/extract.js

@@ -0,0 +1,71 @@
+const DEF_PREFIX = 'definition.';
+const SIGNATURE_MAX = 200;
+// Extract symbol definitions from an already-parsed tree via the grammar's tags
+// query. The caller owns the tree (so definitions and imports can share one
+// parse). Pairs each @definition.<kind> capture with its @name; dedupes by
+// (symbol, line), preferring a specific kind over the generic 'constant'.
+export function extractDefs(query, file, tree) {
+    const byKey = new Map();
+    for (const match of query.matches(tree.rootNode)) {
+        let defCap;
+        let nameCap;
+        for (const c of match.captures) {
+            if (c.name.startsWith(DEF_PREFIX))
+                defCap = c;
+            else if (c.name === 'name')
+                nameCap = c;
+        }
+        if (!defCap || !nameCap)
+            continue;
+        const symbol = nameCap.node.text;
+        // The JS tags exclude constructors via a predicate; web-tree-sitter does not
+        // auto-apply it, so honor the intent here.
+        if (symbol.length === 0 || symbol === 'constructor')
+            continue;
+        const kind = defCap.name.slice(DEF_PREFIX.length);
+        const line = nameCap.node.startPosition.row + 1;
+        const key = `${symbol}:${line}`;
+        // Keep the first match for a (symbol, line), but let a specific kind replace
+        // the generic 'constant' — an exported arrow function is a function, not a
+        // constant, and both patterns match it.
+        const existing = byKey.get(key);
+        const newIsMoreSpecific = existing?.kind === 'constant' && kind !== 'constant';
+        if (existing && !newIsMoreSpecific)
+            continue;
+        byKey.set(key, {
+            symbol,
+            kind,
+            file,
+            line,
+            signature: signatureOf(defCap.node),
+            precisionTier: 'tree-sitter',
+        });
+    }
+    return [...byKey.values()];
+}
+// Honest "signature": the definition's real header text with any block body
+// stripped using the AST (the body node's start) — NOT a text search for `{`,
+// which truncates generic constraints (`<T extends { id }>`), object-typed params
+// (`(x: { a })`), and object const values (`= { a: 1 }`). Definitions with no
+// block body (type aliases, ambient signatures, expression-bodied arrows,
+// non-function consts) keep their full text. Whitespace is collapsed so a wrapped
+// multi-line signature reads on one line; the body is never included.
+function signatureOf(node) {
+    const bodyStart = bodyStartIndex(node);
+    const text = node.text;
+    // web-tree-sitter indices are UTF-16 code units, matching JS string indexing,
+    // so this slice is exact even with non-ASCII identifiers before the body.
+    const header = bodyStart === null ? text : text.slice(0, bodyStart - node.startIndex);
+    return header.replace(/\s+/g, ' ').trim().slice(0, SIGNATURE_MAX);
+}
+// Source index where the definition's block body begins, or null if it has none.
+function bodyStartIndex(node) {
+    const body = node.childForFieldName('body');
+    if (body)
+        return body.startIndex;
+    // An arrow/function assigned to a variable_declarator carries its body on `value`.
+    const valueBody = node.childForFieldName('value')?.childForFieldName('body');
+    if (valueBody && valueBody.type === 'statement_block')
+        return valueBody.startIndex;
+    return null;
+}

package/dist/engine/glob.js

@@ -0,0 +1,35 @@
+// Minimal glob -> RegExp for scoping find_def results by path. Supports `**`
+// (across path segments), `*` (within a segment) and `?`. Paths are posix-style.
+// Intentionally NOT a full glob (no brace/extglob expansion) — sufficient for
+// find_def's optional path scoping. A fuller matcher can replace this in P2 when
+// vocabulary path-locators need richer semantics.
+const REGEX_SPECIAL = /[.+^${}()|[\]\\]/g;
+function globToRegExp(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                // `**` matches across segments; consume a following slash so `**/x`
+                // matches `x` at the root too.
+                re += '.*';
+                i++;
+                if (glob[i + 1] === '/')
+                    i++;
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else {
+            re += c.replace(REGEX_SPECIAL, '\\$&');
+        }
+    }
+    return new RegExp('^' + re + '$');
+}
+export function matchGlob(path, glob) {
+    return globToRegExp(glob).test(path);
+}

package/dist/engine/grammar-registry.js

@@ -0,0 +1,89 @@
+import { Parser, Language, Query } from 'web-tree-sitter';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// Each grammar's tags query is the upstream javascript tags ++ (for TS) the
+// upstream typescript tags ++ arcscope's vetted additions (type aliases, enums,
+// namespaces, exported consts — forms the stock tags omit). The TS grammar is a
+// superset of JS, so the JS patterns compile and match against it; running the TS
+// tags alone would miss most real definitions. Verified by the engine tests.
+const GRAMMARS = {
+    typescript: {
+        wasm: 'tree-sitter-typescript.wasm',
+        queries: ['javascript-tags.scm', 'typescript-tags.scm', 'arcscope-extra-typescript.scm'],
+    },
+    tsx: {
+        wasm: 'tree-sitter-tsx.wasm',
+        queries: ['javascript-tags.scm', 'typescript-tags.scm', 'arcscope-extra-typescript.scm'],
+    },
+    javascript: {
+        wasm: 'tree-sitter-javascript.wasm',
+        queries: ['javascript-tags.scm', 'arcscope-extra-javascript.scm'],
+    },
+};
+const EXT_TO_GRAMMAR = {
+    '.ts': 'typescript',
+    '.mts': 'typescript',
+    '.cts': 'typescript',
+    '.tsx': 'tsx',
+    '.js': 'javascript',
+    '.jsx': 'javascript',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+};
+// The web-tree-sitter WASM runtime is a single global; init it once per process
+// regardless of how many GrammarRegistry instances exist (tests create several).
+let runtimeInit;
+// Lazily loads WASM grammars + compiled tag queries from the vendored, offline
+// grammar directory. Nothing here touches the network.
+export class GrammarRegistry {
+    parser;
+    cache = new Map();
+    dir;
+    constructor(grammarsDir) {
+        this.dir = grammarsDir ?? resolveGrammarsDir();
+    }
+    grammarIdForExt(ext) {
+        return EXT_TO_GRAMMAR[ext];
+    }
+    async ensureInit() {
+        if (!runtimeInit) {
+            runtimeInit = Parser.init({ locateFile: (name) => join(this.dir, name) });
+        }
+        await runtimeInit;
+        if (!this.parser)
+            this.parser = new Parser();
+        return this.parser;
+    }
+    async getForExt(ext) {
+        const id = EXT_TO_GRAMMAR[ext];
+        return id ? this.getGrammar(id) : undefined;
+    }
+    async getGrammar(id) {
+        const cached = this.cache.get(id);
+        if (cached)
+            return cached;
+        await this.ensureInit();
+        const spec = GRAMMARS[id];
+        if (!spec)
+            throw new Error(`unknown grammar id: ${id}`);
+        const language = await Language.load(new Uint8Array(readFileSync(join(this.dir, spec.wasm))));
+        const source = spec.queries.map((q) => readFileSync(join(this.dir, q), 'utf8')).join('\n');
+        const loaded = { id, language, query: new Query(language, source) };
+        this.cache.set(id, loaded);
+        return loaded;
+    }
+}
+// Grammars live in dist/grammars/ in the published package and vendor/grammars/
+// in the source tree (tests run against the latter). Prefer the built location.
+function resolveGrammarsDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const dist = join(here, '..', 'grammars'); // dist/engine -> dist/grammars
+    if (existsSync(dist))
+        return dist;
+    const vendor = join(here, '..', '..', 'vendor', 'grammars'); // src/engine -> vendor/grammars
+    if (existsSync(vendor))
+        return vendor;
+    throw new Error('arcscope: grammar assets not found (looked in dist/grammars and vendor/grammars). ' +
+        'Run `npm run build`, or reinstall the package.');
+}

package/dist/engine/imports.js

@@ -0,0 +1,89 @@
+// Extract import + re-export edges from an already-parsed tree by walking the
+// top-level statements — import/re-export statements are always top-level in ESM,
+// so this is cheap and complete (no full query needed). Verified against real
+// barrels in the de-risking spike. The caller owns the tree.
+export function extractImports(file, tree) {
+    const edges = [];
+    for (const node of tree.rootNode.namedChildren) {
+        if (node.type === 'import_statement') {
+            const edge = fromImport(file, node);
+            if (edge)
+                edges.push(edge);
+        }
+        else if (node.type === 'export_statement') {
+            const edge = fromReExport(file, node);
+            if (edge)
+                edges.push(edge);
+        }
+    }
+    return edges;
+}
+function specifierOf(node) {
+    const src = node.childForFieldName('source');
+    return src ? src.text.slice(1, -1) : null; // strip quotes
+}
+function fromImport(file, node) {
+    const specifier = specifierOf(node);
+    if (specifier === null)
+        return null;
+    const line = node.startPosition.row + 1;
+    const clause = node.namedChildren.find((c) => c.type === 'import_clause');
+    if (!clause)
+        return { file, specifier, kind: 'import', star: false, names: [], line }; // side-effect
+    const names = [];
+    let star = false;
+    for (const c of clause.namedChildren) {
+        if (c.type === 'identifier') {
+            names.push({ imported: 'default', local: c.text }); // default import
+        }
+        else if (c.type === 'namespace_import') {
+            star = true;
+            const id = c.namedChildren.find((x) => x.type === 'identifier');
+            if (id)
+                names.push({ imported: '*', local: id.text });
+        }
+        else if (c.type === 'named_imports') {
+            for (const s of c.namedChildren) {
+                if (s.type !== 'import_specifier')
+                    continue;
+                const n = s.childForFieldName('name');
+                if (!n)
+                    continue;
+                const a = s.childForFieldName('alias');
+                names.push({ imported: n.text, local: (a ?? n).text });
+            }
+        }
+    }
+    return { file, specifier, kind: 'import', star, names, line };
+}
+function fromReExport(file, node) {
+    const specifier = specifierOf(node);
+    if (specifier === null)
+        return null; // a local `export` declaration, not a re-export edge
+    const line = node.startPosition.row + 1;
+    const clause = node.namedChildren.find((c) => c.type === 'export_clause');
+    if (clause) {
+        const names = [];
+        for (const s of clause.namedChildren) {
+            if (s.type !== 'export_specifier')
+                continue;
+            const n = s.childForFieldName('name');
+            if (!n)
+                continue;
+            const a = s.childForFieldName('alias');
+            names.push({ imported: n.text, local: (a ?? n).text }); // local = exported-as name
+        }
+        return { file, specifier, kind: 're-export', star: false, names, line };
+    }
+    // `export * from './m'` or `export * as Agg from './m'`
+    const ns = node.namedChildren.find((c) => c.type === 'namespace_export');
+    const alias = ns?.namedChildren.find((x) => x.type === 'identifier')?.text;
+    return {
+        file,
+        specifier,
+        kind: 're-export',
+        star: true,
+        names: alias ? [{ imported: '*', local: alias }] : [],
+        line,
+    };
+}

package/dist/engine/index-store.js

@@ -0,0 +1,196 @@
+import { readFileSync, statSync } from 'node:fs';
+import { extname, relative, sep } from 'node:path';
+import { discoverFiles } from './discover.js';
+import { extractDefs } from './extract.js';
+import { extractImports } from './imports.js';
+import { matchGlob } from './glob.js';
+// The in-memory index: bare symbol name -> definitions across the repo. No
+// persistent store, no file watcher (a deliberate slice cut). `sync()` is the
+// single idempotent index lifecycle: the first call is a full build; later calls
+// re-discover and re-extract only files whose mtime/size changed, and evict
+// deleted ones. That's the lazy re-index — cheap because unchanged files are
+// never re-read.
+export class IndexStore {
+    root;
+    registry;
+    defs = new Map();
+    files = new Map(); // absolute path -> entry
+    edges = new Map(); // absolute path -> import/re-export edges
+    constructor(root, registry) {
+        this.root = root;
+        this.registry = registry;
+    }
+    get fileCount() {
+        return this.files.size;
+    }
+    get symbolCount() {
+        let n = 0;
+        for (const arr of this.defs.values())
+            n += arr.length;
+        return n;
+    }
+    get edgeCount() {
+        let n = 0;
+        for (const arr of this.edges.values())
+            n += arr.length;
+        return n;
+    }
+    // All definitions across the repo (used by the vocabulary resolver).
+    allDefs() {
+        const out = [];
+        for (const arr of this.defs.values())
+            out.push(...arr);
+        return out;
+    }
+    // All import/re-export edges across the repo (used by the import graph).
+    allEdges() {
+        const out = [];
+        for (const arr of this.edges.values())
+            out.push(...arr);
+        return out;
+    }
+    // The set of indexed files, relative-posix — used to confirm a resolved
+    // module specifier actually points at a file arcscope knows about.
+    relFileSet() {
+        const out = new Set();
+        for (const abs of this.files.keys())
+            out.add(this.relPath(abs));
+        return out;
+    }
+    async sync() {
+        const start = performance.now();
+        const current = discoverFiles(this.root);
+        const currentSet = new Set(current);
+        let removed = 0;
+        for (const abs of [...this.files.keys()]) {
+            if (!currentSet.has(abs)) {
+                this.evict(abs);
+                removed++;
+            }
+        }
+        let changed = 0;
+        for (const abs of current) {
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            const prev = this.files.get(abs);
+            if (prev && prev.mtimeMs === st.mtimeMs && prev.size === st.size)
+                continue;
+            await this.indexFile(abs, st.mtimeMs, st.size);
+            changed++;
+        }
+        return {
+            fileCount: this.files.size,
+            symbolCount: this.symbolCount,
+            changed,
+            removed,
+            elapsedMs: Math.round(performance.now() - start),
+        };
+    }
+    find(symbol, pathGlob) {
+        const arr = this.defs.get(symbol) ?? [];
+        const res = pathGlob ? arr.filter((r) => matchGlob(r.file, pathGlob)) : arr;
+        return [...res].sort(byFileLine);
+    }
+    // Approximate name matches, used only when an exact find() returns nothing — so
+    // the agent doesn't have to guess the precise symbol name. Returns one
+    // representative definition per similarly-named symbol (case-insensitive),
+    // ranked: prefix match, then substring, then the query containing the name.
+    // Matching is by NAME only; the returned locations are still exact.
+    findFuzzy(symbol, pathGlob, limit = 12) {
+        const q = symbol.toLowerCase();
+        const matches = [];
+        for (const [name, recs] of this.defs) {
+            const lower = name.toLowerCase();
+            if (lower === q)
+                continue; // exact is handled by find()
+            let score;
+            if (lower.startsWith(q))
+                score = 0;
+            else if (lower.includes(q))
+                score = 1;
+            // The weakest signal — the query contains the symbol's name — only counts for
+            // substantial names, else tiny symbols like `y`/`ry` pollute every query.
+            else if (lower.length >= 4 && q.includes(lower))
+                score = 2;
+            else
+                continue;
+            const inScope = pathGlob ? recs.filter((r) => matchGlob(r.file, pathGlob)) : recs;
+            if (inScope.length === 0)
+                continue;
+            matches.push({ rec: [...inScope].sort(byFileLine)[0], score });
+        }
+        matches.sort((a, b) => a.score - b.score ||
+            a.rec.symbol.length - b.rec.symbol.length ||
+            (a.rec.symbol < b.rec.symbol ? -1 : 1));
+        return matches.slice(0, limit).map((m) => m.rec);
+    }
+    async indexFile(abs, mtimeMs, size) {
+        this.evict(abs);
+        const grammar = await this.registry.getForExt(extname(abs));
+        if (!grammar)
+            return; // unsupported extension (shouldn't happen after discovery filter)
+        let source;
+        try {
+            source = readFileSync(abs, 'utf8');
+        }
+        catch {
+            return;
+        }
+        const parser = await this.registry.ensureInit();
+        parser.setLanguage(grammar.language);
+        const tree = parser.parse(source);
+        if (!tree)
+            return;
+        const rel = this.relPath(abs);
+        try {
+            const records = extractDefs(grammar.query, rel, tree);
+            const fileEdges = extractImports(rel, tree);
+            const symbols = new Set();
+            for (const r of records) {
+                let arr = this.defs.get(r.symbol);
+                if (!arr) {
+                    arr = [];
+                    this.defs.set(r.symbol, arr);
+                }
+                arr.push(r);
+                symbols.add(r.symbol);
+            }
+            if (fileEdges.length > 0)
+                this.edges.set(abs, fileEdges);
+            this.files.set(abs, { mtimeMs, size, symbols: [...symbols] });
+        }
+        finally {
+            tree.delete();
+        }
+    }
+    evict(abs) {
+        const entry = this.files.get(abs);
+        if (!entry)
+            return;
+        const rel = this.relPath(abs);
+        for (const sym of entry.symbols) {
+            const arr = this.defs.get(sym);
+            if (!arr)
+                continue;
+            const kept = arr.filter((r) => r.file !== rel);
+            if (kept.length)
+                this.defs.set(sym, kept);
+            else
+                this.defs.delete(sym);
+        }
+        this.edges.delete(abs);
+        this.files.delete(abs);
+    }
+    relPath(abs) {
+        const rel = relative(this.root, abs);
+        return sep === '/' ? rel : rel.split(sep).join('/');
+    }
+}
+function byFileLine(a, b) {
+    return a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1;
+}