arcscope 0.0.1

package/dist/engine/module-resolver.js

@@ -0,0 +1,134 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { posix, join } from 'node:path';
+const EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx'];
+// Resolves a module specifier (as written in an import) to the repo-relative file
+// it points at, or null for external/unresolvable specifiers. Handles relative
+// paths and tsconfig `paths` aliases — the one sanctioned config read (spec §4
+// lists tsconfig paths as a secondary signal; no nx.json/project.json/BUILD).
+// File existence is delegated so resolution is tied to arcscope's index, not raw FS.
+export class ModuleResolver {
+    root;
+    fileExists;
+    aliases = null;
+    constructor(root, fileExists) {
+        this.root = root;
+        this.fileExists = fileExists;
+    }
+    resolve(importerRel, specifier) {
+        if (specifier.startsWith('.')) {
+            const base = posix.dirname(importerRel);
+            return this.tryCandidate(posix.normalize(posix.join(base, specifier)));
+        }
+        for (const alias of this.loadAliases()) {
+            const substituted = this.matchAlias(alias, specifier);
+            if (substituted === null)
+                continue;
+            for (const target of substituted) {
+                const hit = this.tryCandidate(posix.normalize(target));
+                if (hit)
+                    return hit;
+            }
+        }
+        return null; // bare specifier (@angular/core, rxjs, …) — external
+    }
+    matchAlias(alias, specifier) {
+        if (!alias.wildcard) {
+            return specifier === alias.prefix ? alias.targets : null;
+        }
+        if (!specifier.startsWith(alias.prefix))
+            return null;
+        const rest = specifier.slice(alias.prefix.length);
+        return alias.targets.map((t) => t.replace('*', rest));
+    }
+    tryCandidate(p) {
+        if (this.fileExists(p))
+            return p; // tsconfig targets often already carry .ts
+        // NodeNext writes a './x.js' specifier for a './x.ts' source — strip the JS
+        // extension so the candidate loop can find the real TS/JS file.
+        const base = p.replace(/\.[cm]?jsx?$/, '');
+        for (const ext of EXTS)
+            if (this.fileExists(base + ext))
+                return base + ext;
+        for (const ext of EXTS)
+            if (this.fileExists(`${base}/index${ext}`))
+                return `${base}/index${ext}`;
+        return null;
+    }
+    loadAliases() {
+        if (this.aliases)
+            return this.aliases;
+        this.aliases = [];
+        for (const name of ['tsconfig.base.json', 'tsconfig.json']) {
+            const file = join(this.root, name);
+            if (!existsSync(file))
+                continue;
+            let config;
+            try {
+                config = JSON.parse(stripJsonc(readFileSync(file, 'utf8')));
+            }
+            catch {
+                continue;
+            }
+            const paths = config.compilerOptions?.paths;
+            if (!paths)
+                continue;
+            const baseUrl = config.compilerOptions?.baseUrl ?? '.';
+            for (const [key, targets] of Object.entries(paths)) {
+                const wildcard = key.endsWith('*');
+                this.aliases.push({
+                    prefix: wildcard ? key.slice(0, -1) : key,
+                    wildcard,
+                    targets: targets.map((t) => posix.normalize(posix.join(baseUrl, t))),
+                });
+            }
+            break; // first tsconfig with paths wins
+        }
+        return this.aliases;
+    }
+}
+// Tolerant JSON-with-comments parse prep: strip // and /* */ comments (respecting
+// string literals) and trailing commas, so real-world tsconfigs parse.
+function stripJsonc(s) {
+    let out = '';
+    let i = 0;
+    let inStr = false;
+    let strCh = '';
+    while (i < s.length) {
+        const c = s[i];
+        const n = s[i + 1];
+        if (inStr) {
+            out += c;
+            if (c === '\\') {
+                out += n ?? '';
+                i += 2;
+                continue;
+            }
+            if (c === strCh)
+                inStr = false;
+            i++;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            inStr = true;
+            strCh = c;
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === '/' && n === '/') {
+            while (i < s.length && s[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (c === '/' && n === '*') {
+            i += 2;
+            while (i < s.length && !(s[i] === '*' && s[i + 1] === '/'))
+                i++;
+            i += 2;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out.replace(/,(\s*[}\]])/g, '$1');
+}

package/dist/engine/ref-scan.js

@@ -0,0 +1,88 @@
+import { Query } from 'web-tree-sitter';
+import { extname } from 'node:path';
+// Compiled once per grammar — every value/type identifier node. `type_identifier`
+// is TS-only; the JavaScript grammar doesn't have that node, so its query must omit
+// it (else Query compilation throws "Bad node name 'type_identifier'").
+const refsQueryCache = new Map();
+const REFS_QUERY_SRC = {
+    typescript: '[(identifier) (type_identifier)] @id',
+    tsx: '[(identifier) (type_identifier)] @id',
+    javascript: '(identifier) @id',
+};
+// Parents where the matching identifier is the *name being declared*, not a
+// reference — excluded so a definition doesn't report itself.
+const DECL_NAME_PARENTS = new Set([
+    'class_declaration',
+    'abstract_class_declaration',
+    'function_declaration',
+    'generator_function_declaration',
+    'function_signature',
+    'interface_declaration',
+    'type_alias_declaration',
+    'enum_declaration',
+    'method_definition',
+    'variable_declarator',
+    'internal_module',
+    'module',
+]);
+// Re-parse one file and find every reference to `localName` (value or type
+// position), classified by refKind. Used by find_refs only on the files the
+// import graph says actually import the symbol — so this never runs repo-wide.
+export async function findOccurrences(registry, rel, source, localName) {
+    const grammar = await registry.getForExt(extname(rel));
+    if (!grammar)
+        return [];
+    const parser = await registry.ensureInit();
+    parser.setLanguage(grammar.language);
+    const tree = parser.parse(source);
+    if (!tree)
+        return [];
+    try {
+        let query = refsQueryCache.get(grammar.id);
+        if (!query) {
+            query = new Query(grammar.language, REFS_QUERY_SRC[grammar.id] ?? '(identifier) @id');
+            refsQueryCache.set(grammar.id, query);
+        }
+        const lines = source.split('\n');
+        const out = [];
+        for (const cap of query.captures(tree.rootNode)) {
+            const node = cap.node;
+            if (node.text !== localName || isDeclarationName(node))
+                continue;
+            out.push({
+                file: rel,
+                line: node.startPosition.row + 1,
+                column: node.startPosition.column + 1,
+                snippet: (lines[node.startPosition.row] ?? '').trim().slice(0, 120),
+                refKind: classify(node),
+            });
+        }
+        return out;
+    }
+    finally {
+        tree.delete();
+    }
+}
+// web-tree-sitter returns fresh Node wrappers per access, so compare by position.
+function isDeclarationName(node) {
+    const p = node.parent;
+    return !!p && DECL_NAME_PARENTS.has(p.type) && p.childForFieldName('name')?.startIndex === node.startIndex;
+}
+function classify(node) {
+    if (node.type === 'type_identifier')
+        return 'type';
+    const p = node.parent;
+    if (!p)
+        return 'identifier';
+    if (p.type === 'call_expression' && p.childForFieldName('function')?.startIndex === node.startIndex)
+        return 'call';
+    if (p.type === 'new_expression' && p.childForFieldName('constructor')?.startIndex === node.startIndex)
+        return 'new';
+    if (p.type === 'member_expression' && p.childForFieldName('object')?.startIndex === node.startIndex)
+        return 'access';
+    if (p.type === 'import_specifier' || p.type === 'namespace_import' || p.type === 'import_clause')
+        return 'import';
+    if (p.type === 'extends_clause' || p.type === 'class_heritage' || p.type === 'implements_clause')
+        return 'extends';
+    return 'identifier';
+}

package/dist/engine/types.js

@@ -0,0 +1,2 @@
+// Shared engine shapes.
+export {};

package/dist/grammars/arcscope-extra-javascript.scm

@@ -0,0 +1,9 @@
+; arcscope-authored additions, appended to the upstream javascript tags.scm.
+; Captures exported non-function const/let bindings (upstream only tags
+; function-valued declarators). Scoped to export_statement so file-local consts
+; don't pollute the index. Verified to compile against the javascript grammar.
+
+(export_statement
+  (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name))) @definition.constant

package/dist/grammars/arcscope-extra-typescript.scm

@@ -0,0 +1,23 @@
+; arcscope-authored additions, appended to the upstream javascript + typescript
+; tags.scm. The stock tree-sitter tags omit these TS definition forms, which an
+; agent realistically navigates to; without them find_def loses to grep on TS.
+; Verified to compile against the typescript AND tsx grammars (web-tree-sitter 0.26.9),
+; and to capture the forms below on real code (see the engine extraction tests).
+; Capture convention matches upstream: @definition.<kind> on the node, @name on its identifier.
+
+(type_alias_declaration
+  name: (type_identifier) @name) @definition.type
+
+(enum_declaration
+  name: (identifier) @name) @definition.enum
+
+; `namespace X {}` parses as internal_module (upstream only tags `module "x" {}`).
+(internal_module
+  name: (identifier) @name) @definition.module
+
+; Exported const/let bindings of any value (upstream only tags function-valued ones).
+; Scoped to export_statement so file-local consts don't pollute the index.
+(export_statement
+  (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name))) @definition.constant

package/dist/grammars/javascript-tags.scm

@@ -0,0 +1,99 @@
+(
+  (comment)* @doc
+  .
+  (method_definition
+    name: (property_identifier) @name) @definition.method
+  (#not-eq? @name "constructor")
+  (#strip! @doc "^[\\s\\*/]+|^[\\s\\*/]$")
+  (#select-adjacent! @doc @definition.method)
+)
+
+(
+  (comment)* @doc
+  .
+  [
+    (class
+      name: (_) @name)
+    (class_declaration
+      name: (_) @name)
+  ] @definition.class
+  (#strip! @doc "^[\\s\\*/]+|^[\\s\\*/]$")
+  (#select-adjacent! @doc @definition.class)
+)
+
+(
+  (comment)* @doc
+  .
+  [
+    (function_expression
+      name: (identifier) @name)
+    (function_declaration
+      name: (identifier) @name)
+    (generator_function
+      name: (identifier) @name)
+    (generator_function_declaration
+      name: (identifier) @name)
+  ] @definition.function
+  (#strip! @doc "^[\\s\\*/]+|^[\\s\\*/]$")
+  (#select-adjacent! @doc @definition.function)
+)
+
+(
+  (comment)* @doc
+  .
+  (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name
+      value: [(arrow_function) (function_expression)]) @definition.function)
+  (#strip! @doc "^[\\s\\*/]+|^[\\s\\*/]$")
+  (#select-adjacent! @doc @definition.function)
+)
+
+(
+  (comment)* @doc
+  .
+  (variable_declaration
+    (variable_declarator
+      name: (identifier) @name
+      value: [(arrow_function) (function_expression)]) @definition.function)
+  (#strip! @doc "^[\\s\\*/]+|^[\\s\\*/]$")
+  (#select-adjacent! @doc @definition.function)
+)
+
+(assignment_expression
+  left: [
+    (identifier) @name
+    (member_expression
+      property: (property_identifier) @name)
+  ]
+  right: [(arrow_function) (function_expression)]
+) @definition.function
+
+(pair
+  key: (property_identifier) @name
+  value: [(arrow_function) (function_expression)]) @definition.function
+
+(
+  (call_expression
+    function: (identifier) @name) @reference.call
+  (#not-match? @name "^(require)$")
+)
+
+(call_expression
+  function: (member_expression
+    property: (property_identifier) @name)
+  arguments: (_) @reference.call)
+
+(new_expression
+  constructor: (_) @name) @reference.class
+
+(export_statement value: (assignment_expression left: (identifier) @name right: ([
+ (number)
+ (string)
+ (identifier)
+ (undefined)
+ (null)
+ (new_expression)
+ (binary_expression)
+ (call_expression)
+]))) @definition.constant

package/dist/grammars/typescript-tags.scm

@@ -0,0 +1,23 @@
+(function_signature
+  name: (identifier) @name) @definition.function
+
+(method_signature
+  name: (property_identifier) @name) @definition.method
+
+(abstract_method_signature
+  name: (property_identifier) @name) @definition.method
+
+(abstract_class_declaration
+  name: (type_identifier) @name) @definition.class
+
+(module
+  name: (identifier) @name) @definition.module
+
+(interface_declaration
+  name: (type_identifier) @name) @definition.interface
+
+(type_annotation
+  (type_identifier) @name) @reference.type
+
+(new_expression
+  constructor: (identifier) @name) @reference.class

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { logError } from './log.js';
+// Single bin, branches on argv. Subcommands are imported lazily so `init` doesn't
+// pay to load the MCP SDK and `serve` starts with a clean module graph.
+const command = process.argv[2];
+const root = process.cwd();
+try {
+    switch (command) {
+        case 'init': {
+            const { init } = await import('./init/init.js');
+            await init(root);
+            break;
+        }
+        case 'serve': {
+            const { serve } = await import('./server/serve.js');
+            await serve(root);
+            break;
+        }
+        default: {
+            process.stderr.write('arcscope — fully-local, architecture-aware code-navigation MCP server\n\n' +
+                'Usage:\n' +
+                '  arcscope init    Index this repo, write .mcp.json, and update .gitignore\n' +
+                '  arcscope serve   Run the MCP server over stdio (spawned by your MCP client)\n');
+            process.exit(command ? 1 : 0);
+        }
+    }
+}
+catch (err) {
+    logError(err instanceof Error ? (err.stack ?? err.message) : err);
+    process.exit(1);
+}

package/dist/init/init.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, relative } from 'node:path';
+import { GrammarRegistry } from '../engine/grammar-registry.js';
+import { IndexStore } from '../engine/index-store.js';
+// `arcscope init`: index the repo once (the acceptance measurement), register the
+// server for the MCP client offline, and ensure local cache files are gitignored.
+// init is a human-facing CLI, so writing to stdout here is fine — the stdout
+// hygiene rule applies to `serve`'s JSON-RPC stream, not this command.
+export async function init(root) {
+    const out = (s) => process.stdout.write(s + '\n');
+    // 1. Index pass — measure cold-index time + symbol count on the real tree.
+    const store = new IndexStore(root, new GrammarRegistry());
+    const stats = await store.sync();
+    out(`arcscope: indexed ${stats.fileCount} files, ${stats.symbolCount} symbols in ${stats.elapsedMs}ms`);
+    // 2. Registration — point the client at the locally-resolved bin so server
+    //    spawn is offline and deterministic (never `npx arcscope serve`). Derive the
+    //    bin path from this module (dist/init/init.js -> dist/index.js) rather than
+    //    process.argv[1], so it's correct even when invoked via a symlink/wrapper.
+    const binPath = fileURLToPath(new URL('../index.js', import.meta.url));
+    const mcpPath = join(root, '.mcp.json');
+    writeMcpJson(mcpPath, binPath);
+    out(`arcscope: wrote ${relative(root, mcpPath) || '.mcp.json'} (node -> ${binPath} serve)`);
+    // 3. Keep regenerable local state out of git.
+    if (ensureGitignore(root))
+        out('arcscope: updated .gitignore (.arcscope/* ignored, vocab.yaml committed)');
+    out('arcscope: ready — reconnect your MCP client to load the server.');
+}
+export function writeMcpJson(mcpPath, binPath) {
+    let config = {};
+    if (existsSync(mcpPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(mcpPath, 'utf8'));
+            if (parsed && typeof parsed === 'object')
+                config = parsed;
+        }
+        catch {
+            // unreadable/invalid -> start fresh rather than fail init
+        }
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== 'object')
+        config.mcpServers = {};
+    config.mcpServers['arcscope'] = { command: 'node', args: [binPath, 'serve'] };
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+// Ignore the regenerable local cache (index/usage/anchors) but COMMIT the
+// vocabulary — `.arcscope/vocab.yaml` is the repo's declared knowledge and must
+// travel with it. Note: re-including a file requires ignoring `.arcscope/*` (not
+// the whole `.arcscope/` directory), so an old wholesale ignore is upgraded.
+export function ensureGitignore(root) {
+    const p = join(root, '.gitignore');
+    const lines = (existsSync(p) ? readFileSync(p, 'utf8') : '').split('\n');
+    if (lines.some((l) => l.trim() === '.arcscope/*'))
+        return false; // already in the right shape
+    const kept = lines
+        .filter((l) => {
+        const t = l.trim();
+        return t !== '.arcscope/' && t !== '.arcscope' && !/^#\s*arcscope local index/i.test(t);
+    })
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/\s+$/, '');
+    const block = '# arcscope: ignore the local cache (index/usage/anchors); commit the vocabulary\n.arcscope/*\n!.arcscope/vocab.yaml\n';
+    writeFileSync(p, kept ? `${kept}\n\n${block}` : block, 'utf8');
+    return true;
+}

package/dist/knowledge/drift.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+function sha1(s) {
+    return createHash('sha1').update(s).digest('hex').slice(0, 16);
+}
+// Symbol anchors hash the def's kind+signature (so a header change drifts but a
+// pure line move does not); path anchors hash the file's content.
+export function computeAnchors(root, resolved) {
+    const byKey = new Map();
+    const fileCache = new Map();
+    for (const r of resolved) {
+        let anchor;
+        if (r.via === 'symbol') {
+            anchor = { key: `${r.file}#${r.symbol}`, hash: sha1(`${r.kind} ${r.signature ?? ''}`) };
+        }
+        else {
+            let content = fileCache.get(r.file);
+            if (content === undefined) {
+                try {
+                    content = readFileSync(join(root, r.file), 'utf8');
+                }
+                catch {
+                    content = '';
+                }
+                fileCache.set(r.file, content);
+            }
+            anchor = { key: r.file, hash: sha1(content) };
+        }
+        byKey.set(anchor.key, anchor); // dedupe overlapping locators
+    }
+    return [...byKey.values()];
+}
+export function compareDrift(current, baseline) {
+    const cur = new Map(current.map((a) => [a.key, a.hash]));
+    const base = new Map(baseline.map((a) => [a.key, a.hash]));
+    const added = [...cur.keys()].filter((k) => !base.has(k));
+    const removed = [...base.keys()].filter((k) => !cur.has(k));
+    const changed = [...cur.keys()].filter((k) => base.has(k) && base.get(k) !== cur.get(k));
+    return { status: added.length || removed.length || changed.length ? 'drifted' : 'fresh', added, removed, changed };
+}
+function anchorsPath(root) {
+    return join(root, '.arcscope', 'anchors.json');
+}
+// Local, gitignored baseline (per the chosen drift model).
+export function loadAnchorStore(root) {
+    const p = anchorsPath(root);
+    if (!existsSync(p))
+        return { concepts: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        if (parsed && typeof parsed === 'object' && 'concepts' in parsed)
+            return parsed;
+    }
+    catch {
+        // corrupt -> start fresh
+    }
+    return { concepts: {} };
+}
+export function baselineFor(store, conceptId) {
+    return store.concepts[conceptId]?.anchors;
+}
+export function captureBaseline(root, conceptId, anchors, nowIso) {
+    const store = loadAnchorStore(root);
+    store.concepts[conceptId] = { anchors, capturedAt: nowIso };
+    mkdirSync(join(root, '.arcscope'), { recursive: true });
+    writeFileSync(anchorsPath(root), JSON.stringify(store, null, 2) + '\n', 'utf8');
+}

package/dist/knowledge/locator.js

@@ -0,0 +1,24 @@
+const KIND_ALIASES = { const: 'constant' };
+// Parse a symbol locator query: "<kind> <namePattern> [= <valueConstraint>]".
+// Examples: "interface I*Repository", "class GraphReducer",
+// "const *_REPOSITORY = InjectionToken", "method normalizeElement".
+// Pure string parsing — no regex injection, no shell-out (invariant 4).
+export function parseSymbolQuery(query) {
+    let head = query.trim();
+    let valueConstraint;
+    const eq = head.indexOf('=');
+    if (eq >= 0) {
+        valueConstraint = head.slice(eq + 1).trim() || undefined;
+        head = head.slice(0, eq).trim();
+    }
+    const sp = head.indexOf(' ');
+    if (sp < 0) {
+        throw new Error(`invalid symbol locator query: "${query}" (expected "<kind> <namePattern> [= <value>]")`);
+    }
+    const rawKind = head.slice(0, sp).trim();
+    const namePattern = head.slice(sp + 1).trim();
+    if (rawKind.length === 0 || namePattern.length === 0) {
+        throw new Error(`invalid symbol locator query: "${query}" (missing kind or name pattern)`);
+    }
+    return { kind: KIND_ALIASES[rawKind] ?? rawKind, namePattern, valueConstraint };
+}

package/dist/knowledge/resolver.js

@@ -0,0 +1,45 @@
+import { matchGlob } from '../engine/glob.js';
+import { parseSymbolQuery } from './locator.js';
+// Resolve a concept LIVE against the current index. Symbol locators filter the def
+// index (reuse P0); path locators filter the file set. Staged concepts resolve
+// each stage in order and tag results with the stage title. Everything routes
+// through the engine — no shell-out.
+export function resolveConcept(store, concept) {
+    if (concept.stages) {
+        const out = [];
+        for (const stage of concept.stages) {
+            for (const loc of resolveLocator(store, stage))
+                out.push({ ...loc, stage: stage.title });
+        }
+        return out;
+    }
+    return (concept.locators ?? []).flatMap((loc) => resolveLocator(store, loc));
+}
+function resolveLocator(store, loc) {
+    if (loc.kind === 'symbol') {
+        const { kind, namePattern, valueConstraint } = parseSymbolQuery(loc.query);
+        return store
+            .allDefs()
+            .filter((d) => d.kind === kind &&
+            matchGlob(d.symbol, namePattern) &&
+            (loc.in === undefined || matchGlob(d.file, loc.in)) &&
+            (valueConstraint === undefined || d.signature.includes(valueConstraint)))
+            .sort(byFileLine)
+            .map((d) => ({
+            file: d.file,
+            line: d.line,
+            kind: d.kind,
+            symbol: d.symbol,
+            signature: d.signature,
+            via: 'symbol',
+            precisionTier: 'tree-sitter',
+        }));
+    }
+    return [...store.relFileSet()]
+        .filter((f) => matchGlob(f, loc.glob) && (loc.in === undefined || matchGlob(f, loc.in)))
+        .sort()
+        .map((f) => ({ file: f, kind: 'file', via: 'path', precisionTier: 'tree-sitter' }));
+}
+function byFileLine(a, b) {
+    return a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1;
+}

package/dist/knowledge/types.js

@@ -0,0 +1,2 @@
+// The architecture vocabulary: named concepts bound to engine-resolved locators.
+export {};