@spectie/adapter-javascript 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 spectie contributors
+
+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

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# rf.javascript 1.0.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+当前接入使用协议 1：`spectie adapter add /本包目录`，自动注册并精确选择；Node 包先在本包目录执行 `npm ci --ignore-scripts`。共享运行时、依赖声明及完整流程见 [扩展说明](https://github.com/fanglinwei/spectie/blob/main/docs/ADAPTERS.md)。
+
+Independent adapter, protocol 1 / manifest schema 1. Requires Node.js >=22; actual parser versions are in adapter.json and package-lock.json. Dependencies belong to this package, never the analyzed application.
+
+For source installation: run `npm ci --ignore-scripts --no-audit --no-fund --prefix /absolute/package-directory`. A complete offline artifact already includes those dependencies and needs no npm install.
+
+Explicit registration (executes only this chosen adapter's self-check):
+
+```sh
+python3 /absolute/path/rf.py --project /absolute/project adapter-register --manifest /absolute/package-directory/adapter.json
+```
+
+Then use the core's adapter-select command to explicitly lock `rf.javascript@1.0.0` in the project. Registration alone does not select or approve any requirement. Multiple versions may coexist; no auto-updates. The executable reads one JSON request from stdin and writes one JSON response to stdout; diagnostics use stderr. Subprocess separation is not an OS sandbox.
+
+Capabilities: language.js-ts. Category: language. All observations are static source facts, never business verification. Detailed supported concrete versions and limitations are recorded by the package manifest and [adapter guide](https://github.com/fanglinwei/spectie/blob/main/docs/ADAPTERS.md).
+
+This adapter proves local component registration against the default exported configuration. Vue-provided template-expression units reuse this package's TypeScript parser and return template_use facts with resolved declaration spans or explicit unknown diagnostics; template local scopes remain unknown. No expression is executed.
+
+保留同名重载事实及歧义诊断，impact 退回文件粒度，不据缺失事实误报符号增删；默认导出配置中的静态本地组件注册也记录绑定，无法定位目标时保留 unknown 并阻止同名自动导入。
+
+复用每份源码的 UTF-8 字节位置索引，减少重复扫描；事实、原文跨度和指纹算法保持不变。

package/adapter.json

@@ -0,0 +1,49 @@
+{
+  "manifest_schema": "1",
+  "adapter_id": "rf.javascript",
+  "version": "1.0.0",
+  "category": "language",
+  "protocol": "1",
+  "capabilities": [
+    {
+      "id": "language.js-ts",
+      "phase": "language",
+      "input_types": [
+        ".js",
+        ".jsx",
+        ".ts",
+        ".tsx",
+        ".mjs",
+        ".cjs"
+      ],
+      "requires": []
+    }
+  ],
+  "entry": [
+    "node",
+    "{package}/adapter.mjs"
+  ],
+  "runtime": {
+    "name": "node",
+    "minimum": "22"
+  },
+  "requires": [],
+  "parsers": {
+    "typescript": "5.9.3"
+  },
+  "algorithms": [
+    "web-raw-span-v1"
+  ],
+  "limits": [
+    "static_only",
+    "no_project_execution"
+  ],
+  "resolution_extensions": [
+    ".js",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".mjs",
+    ".cjs"
+  ]
+}

package/adapter.mjs

@@ -0,0 +1,190 @@
+import path from 'node:path/posix';
+import {serve, language, documents, diagnostic, span} from '@spectie/adapter';
+await serve(async metadata => {
+ const {default:ts} = await import('typescript');
+ if(ts.version !== '5.9.3') throw Error('TypeScript version mismatch');
+ function parse(source,filename,inputType) {
+  const kind=inputType.endsWith('x')?(inputType==='.tsx'?ts.ScriptKind.TSX:ts.ScriptKind.JSX):inputType==='.ts'?ts.ScriptKind.TS:ts.ScriptKind.JS;
+  const sf=ts.createSourceFile(filename,source,ts.ScriptTarget.Latest,true,kind);
+  const program=ts.createProgram([filename],{noLib:true,noResolve:true,allowJs:true,allowNonTsExtensions:true,target:ts.ScriptTarget.Latest}, {
+   getSourceFile:n=>n===filename?sf:undefined,getDefaultLibFileName:()=>'',writeFile:()=>{},getCurrentDirectory:()=>'',getDirectories:()=>[],fileExists:n=>n===filename,readFile:n=>n===filename?source:undefined,getCanonicalFileName:n=>n,useCaseSensitiveFileNames:()=>true,getNewLine:()=> '\n'
+  });
+  return {sf,checker:program.getTypeChecker()};
+ }
+ const analyzeScripts = await language({
+  analyze(doc) {
+   const out={facts:[],diagnostics:[]}, source=doc.text;
+   const {sf,checker}=parse(source,doc.path,doc.inputType);
+   if(sf.parseDiagnostics.length) {diagnostic(out,'parse_error',doc.path,'TypeScript syntax diagnostics; file fallback');return {...out,complete:false};}
+   const imports=new Map(), importSymbols=new Map(), names=new Map();
+   const at=n=>doc.span(n.getStart(sf,false),n.end);
+   const add=(kind,n,extra={})=>{const f={kind,...at(n),...extra};out.facts.push(f);return f;};
+   const ref=(n,specifier,name='import',data={})=>add('reference',n,{specifier,name,data});
+   const bind=(name,decl,specifier,imported)=>{
+    imports.set(name,{specifier,imported}); importSymbols.set(checker.getSymbolAtLocation(decl),{name,specifier,imported});
+    add('binding',decl,{name,specifier,data:{role:'import',imported,unit_role:doc.role}});
+   };
+   for(const stmt of sf.statements) {
+    if(ts.isImportDeclaration(stmt)&&ts.isStringLiteral(stmt.moduleSpecifier)) {
+     const spec=stmt.moduleSpecifier.text;ref(stmt.moduleSpecifier,spec,/\.(css|scss|sass|less|styl|svg|png|jpg|woff2)(?:[?#]|$)/.test(spec)?'resource_import':'import');const c=stmt.importClause;
+     if(c?.name)bind(c.name.text,c.name,spec,'default');
+     if(c?.namedBindings) {
+      if(ts.isNamespaceImport(c.namedBindings))bind(c.namedBindings.name.text,c.namedBindings.name,spec,'*');
+      else for(const b of c.namedBindings.elements)bind(b.name.text,b.name,spec,b.propertyName?.text||b.name.text);
+     }
+    }
+    if(ts.isExportDeclaration(stmt)) {
+     if(stmt.moduleSpecifier&&ts.isStringLiteral(stmt.moduleSpecifier))ref(stmt.moduleSpecifier,stmt.moduleSpecifier.text,'reexport');
+     add('export',stmt,{name:stmt.exportClause?.getText(sf)||'*'});
+    }
+   }
+   function owner(n) {
+    const parts=[]; for(let p=n.parent;p&&!ts.isSourceFile(p);p=p.parent) {
+     if((ts.isClassDeclaration(p)||ts.isFunctionDeclaration(p)||ts.isMethodDeclaration(p)||ts.isPropertyAssignment(p)||ts.isVariableDeclaration(p))&&p.name&& (ts.isIdentifier(p.name)||ts.isStringLiteral(p.name)))parts.unshift(p.name.text);
+    }
+    return parts;
+   }
+   function symbol(n,name,range=n) {
+    const key=[...owner(n),name].join('.');
+    const fact=doc.symbol({start:range.getStart(sf,false),end:range.end,name:key,data:{unit_role:doc.role}});
+    out.facts.push(fact);
+    names.set(key,[...(names.get(key)||[]),fact]);
+   }
+   function imported(n) {
+    return ts.isIdentifier(n)?importSymbols.get(checker.getSymbolAtLocation(n)):null;
+   }
+   const propertyName=n=>n?.name&&(ts.isIdentifier(n.name)||ts.isStringLiteral(n.name))?n.name.text:null;
+   function object(n,seen=new Set()) {
+    if(!n||seen.has(n))return null;seen.add(n);
+    if(ts.isObjectLiteralExpression(n)){
+     const keys=n.properties.map(propertyName);
+     return keys.every(k=>k!==null)&&new Set(keys).size===keys.length?n:null;
+    }
+    if(ts.isParenthesizedExpression(n)||ts.isAsExpression(n)||ts.isSatisfiesExpression(n))return object(n.expression,seen);
+    if(ts.isIdentifier(n)){
+     const d=checker.getSymbolAtLocation(n)?.valueDeclaration;
+     if(d&&ts.isVariableDeclaration(d)&&(d.parent.flags&ts.NodeFlags.Const))return object(d.initializer,seen);
+    }
+    if(ts.isCallExpression(n)){
+     const b=imported(n.expression),e=n.expression;
+     if((b?.specifier==='vue'&&b.imported==='defineComponent')||(ts.isPropertyAccessExpression(e)&&e.name.text==='extend'&&imported(e.expression)?.specifier==='vue'&&imported(e.expression)?.imported==='default'))return object(n.arguments[0],seen);
+    }
+    return null;
+   }
+   const options=new Set(sf.statements.filter(n=>ts.isExportAssignment(n)&&!n.isExportEquals).map(n=>object(n.expression)).filter(Boolean));
+   const expose=(n,name)=>add('binding',n,{name,data:{role:'template_declaration',unit_role:doc.role}});
+   if(doc.role==='script-setup')for(const stmt of sf.statements){
+    if((ts.isFunctionDeclaration(stmt)||ts.isClassDeclaration(stmt))&&stmt.name)expose(stmt.name,stmt.name.text);
+    if(ts.isVariableStatement(stmt))for(const d of stmt.declarationList.declarations)if(ts.isIdentifier(d.name))expose(d.name,d.name.text);
+   }
+   for(const option of options)for(const prop of option.properties){
+    const name=propertyName(prop);
+    if(['methods','computed','props'].includes(name)&&ts.isPropertyAssignment(prop)){
+     const value=object(prop.initializer);
+     if(value)for(const member of value.properties)if(member.name&&(ts.isIdentifier(member.name)||ts.isStringLiteral(member.name)))expose(member.name,member.name.text);
+     if(name==='props'&&ts.isArrayLiteralExpression(prop.initializer))for(const item of prop.initializer.elements)if(ts.isStringLiteral(item))expose(item,item.text);
+    }
+    if(['data','setup'].includes(name)){
+     const fn=ts.isMethodDeclaration(prop)?prop:ts.isPropertyAssignment(prop)?prop.initializer:null;
+     if(fn?.body&&ts.isBlock(fn.body))for(const stmt of fn.body.statements)if(ts.isReturnStatement(stmt)){
+      const value=object(stmt.expression);
+      if(value)for(const member of value.properties)if(member.name&&(ts.isIdentifier(member.name)||ts.isStringLiteral(member.name)))expose(member.name,member.name.text);
+     }
+    }
+   }
+   function walk(n) {
+    if((ts.isFunctionDeclaration(n)||ts.isClassDeclaration(n))&&!n.name)diagnostic(out,"anonymous_owner_fallback",doc.path,"Anonymous declaration; enclosing file fallback");
+    if((ts.isFunctionDeclaration(n)||ts.isClassDeclaration(n)||ts.isMethodDeclaration(n)||ts.isGetAccessor(n)||ts.isSetAccessor(n))&&n.name) {
+     if(ts.isIdentifier(n.name)||ts.isStringLiteral(n.name))symbol(n,n.name.text);
+     else diagnostic(out,'ambiguous_symbol',doc.path,'Computed declaration name; file fallback');
+    }
+    if(ts.isVariableStatement(n)) for(const d of n.declarationList.declarations) {
+     if(ts.isIdentifier(d.name))symbol(d,d.name.text,n);
+     else diagnostic(out,'ambiguous_symbol',doc.path,'Destructured variable; file fallback');
+    }
+    if(ts.isPropertyAssignment(n)&&n.name&&(ts.isArrowFunction(n.initializer)||ts.isFunctionExpression(n.initializer))) {
+     if(ts.isIdentifier(n.name)||ts.isStringLiteral(n.name))symbol(n,n.name.text);
+    }
+    if((ts.isArrowFunction(n)||ts.isFunctionExpression(n))&&!ts.isVariableDeclaration(n.parent)&&!ts.isPropertyAssignment(n.parent))diagnostic(out,'anonymous_owner_fallback',doc.path,'Anonymous callback retained by enclosing span/file');
+    if(ts.isIdentifier(n)) {
+     const b=imported(n);
+     if(b && !ts.isImportSpecifier(n.parent)&&!ts.isImportClause(n.parent)&&!ts.isNamespaceImport(n.parent))ref(n,b.specifier,'use',{local:b.name,imported:b.imported});
+    }
+    if(ts.isObjectLiteralExpression(n)) for(const prop of n.properties) {
+     const value=ts.isShorthandPropertyAssignment(prop)?prop.name:ts.isPropertyAssignment(prop)?prop.initializer:null;
+     const b=value&&(ts.isShorthandPropertyAssignment(prop)?importSymbols.get(checker.getShorthandAssignmentValueSymbol(prop)):imported(value));
+     const owner=ts.isPropertyAssignment(n.parent)?propertyName(n.parent):'',component_export=owner==='components'&&options.has(n.parent.parent)&&object(n)===n;
+     if((b||component_export)&&prop.name&&(ts.isIdentifier(prop.name)||ts.isStringLiteral(prop.name))) {
+      add('binding',prop,{name:prop.name.text,...(b?{specifier:b.specifier}:{}),data:{role:'object_member',owner,component_export,...(b?{local:b.name,imported:b.imported}:{})}});
+     }
+    }
+    if(ts.isCallExpression(n)) {
+     if(n.expression.kind===ts.SyntaxKind.ImportKeyword||n.expression.getText(sf)==='require') {
+      diagnostic(out,'dynamic_loading_unknown',doc.path,'Dynamic import/require not resolved');
+     }
+     if(ts.isPropertyAccessExpression(n.expression)&&n.expression.name.text==='component') {
+      const [name,value]=n.arguments,b=value&&imported(value);
+      let receiver=n.expression.expression, proven=false, api='';
+      const root=imported(receiver);
+      if(root?.specifier==='vue' && root.imported==='default') {proven=true;api='Vue.component';}
+      if(ts.isIdentifier(receiver)) {
+       const decl=checker.getSymbolAtLocation(receiver)?.valueDeclaration;
+       if(decl&&ts.isVariableDeclaration(decl)&&decl.initializer&&ts.isCallExpression(decl.initializer)) {
+        const factory=imported(decl.initializer.expression);
+        if(factory?.specifier==='vue'&&factory.imported==='createApp'){proven=true;api='app.component';}
+       }
+      }
+      if(proven&&name&&ts.isStringLiteral(name)&&b)add('binding',n,{name:name.text,specifier:b.specifier,data:{role:'global_component',api}});
+      else diagnostic(out,'dynamic_registration_unknown',doc.path,'Component registration cannot be proved statically');
+     }
+    }
+    if(ts.isPropertyAccessExpression(n)&&ts.isPropertyAccessExpression(n.expression)&&['import.meta.env','process.env'].includes(n.expression.getText(sf)))add('environment_key',n.name,{name:n.name.text});
+    if(ts.isElementAccessExpression(n)&&['import.meta.env','process.env'].includes(n.expression.getText(sf))) {
+     if(n.argumentExpression&&ts.isStringLiteral(n.argumentExpression))add('environment_key',n,{name:n.argumentExpression.text});
+     else diagnostic(out,'dynamic_environment_key',doc.path,'Environment values never read');
+    }
+    ts.forEachChild(n,walk);
+   }
+   walk(sf);
+   for(const [name,fs] of names)if(fs.length>1)diagnostic(out,'ambiguous_symbol',doc.path,`Duplicate/overloaded symbol ${name}; file fallback`);
+   return out;
+  },
+ })(metadata);
+ return async input => {
+  const out=await analyzeScripts({...input,units:input.units.filter(u=>!u.role.startsWith('template-expression'))});
+  const docs=documents(input);
+  for(const unit of input.units.filter(u=>u.role.startsWith('template-expression'))){
+   const doc=docs.get(unit.path);
+   if(doc.text===null)continue;
+   const source=new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(doc.raw.subarray(unit.start,unit.end));
+   const unknown=()=>{
+    out.facts.push({kind:'template_use',path:unit.path,start:unit.start,end:unit.end,name:source,data:{role:'binding_use',status:'unknown'}});
+    diagnostic(out,'template_binding_unknown',unit.path,'Template scope or expression cannot be proved statically: '+source);
+   };
+   // shortcut: template local scopes remain unknown until lexical template scope resolution is supported.
+   if(unit.role.endsWith('-scoped')){unknown();out.processed.push(unit);continue;}
+   let prefix=1,{sf,checker}=parse('('+source+')',unit.path,unit.input_type);
+   if(sf.parseDiagnostics.length){prefix=0;({sf,checker}=parse(source,unit.path,unit.input_type));}
+   if(sf.parseDiagnostics.length){unknown();continue;}
+   const resolveSource=f=>path.normalize(path.join(path.dirname(f.path),f.specifier));
+   const owners=new Set([unit.path,...input.facts.filter(f=>f.kind==='reference'&&f.name==='sfc_external_source'&&f.data?.role==='template'&&resolveSource(f)===unit.path).map(f=>f.path)]);
+   const scripts=new Set([...owners,...input.facts.filter(f=>f.kind==='reference'&&f.name==='sfc_external_source'&&f.data?.role==='script'&&owners.has(f.path)).map(resolveSource)]);
+   const bindings=out.facts.filter(f=>f.kind==='binding'&&scripts.has(f.path)&&(f.data?.role==='template_declaration'||(f.data?.role==='import'&&f.data.unit_role==='script-setup')));
+   function uses(n){
+    if(ts.isIdentifier(n)){
+     const p=n.parent,shorthand=ts.isShorthandPropertyAssignment(p);
+     const property=(ts.isPropertyAccessExpression(p)&&p.name===n)||(ts.isPropertyAssignment(p)&&p.name===n);
+     const local=shorthand?checker.getShorthandAssignmentValueSymbol(p):checker.getSymbolAtLocation(n);
+     if(!property&&!local?.valueDeclaration&&!(n.text==='$event'&&unit.role.includes('-event'))){
+      const candidates=bindings.filter(f=>f.name===n.text),binding=candidates.length===1?candidates[0]:null;
+      out.facts.push({kind:'template_use',...span(unit.path,source,n.getStart(sf)-prefix,n.end-prefix,unit.start),name:n.text,data:{role:'binding_use',status:binding?'resolved':'unknown',...(binding?{binding}:{} )}});
+      if(!binding)diagnostic(out,'template_binding_unknown',unit.path,'No unique exposed declaration for '+n.text);
+     }
+    }
+    ts.forEachChild(n,uses);
+   }
+   uses(sf);out.processed.push(unit);
+  }
+  out.processed=[...new Set(out.processed)];return out;
+ };
+}, import.meta.url);

package/node_modules/@spectie/adapter/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 spectie contributors
+
+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/node_modules/@spectie/adapter/README.md

@@ -0,0 +1,16 @@
+# @spectie/adapter
+
+协议 1 的 Node 22+ 适配运行时，独立于 Python 核心。
+
+- `run(language({analyze, offsets, load}), import.meta.url)`：普通语言包。
+- `serve(async metadata => analyzeBatch, import.meta.url)`：跨文件、多阶段包。
+- `documents(input)`：核对文件 SHA-256 并解码，非 UTF-8 的 text 为 null。
+- `doc.span(start, end)`：按当前文档坐标生成原文件范围。
+- `span(path, text, start, end, byteOffset=0)`：UTF-16 到 UTF-8 位置转换。
+- `output()`、`diagnostic(...)`：批量结果与诊断构造。
+
+package.json 的 spectie 字段声明 capabilities，可选 parsers、algorithms 等；不必重复版本。运行时从 adapter.json（若存在）或 package.json 读取清单。详见 [公共 Interface](../../docs/ADAPTERS.md)。language 的 analyze 必须返回对象；{} 是成功空结果，complete:false 表示部分处理，抛异常不会记录完整覆盖。
+
+开发时使用 `file:../../adapter-runtime/node` 依赖并配置 `install-links=true`，修改共享运行时后需重新安装本地副本。四个现有 Node 包 bundle 运行时，npm/offline 包不依赖仓库外部相对路径。扩展也可使用 registry 中已发布的准确运行时版本；从 GitHub Release 获取 SDK tgz 后，可用 `npm install /包/spectie-adapter-1.0.0.tgz` 安装。
+
+打包本运行时：`npm pack --pack-destination /tmp`。只导出 index.mjs，不导入核心私有实现。

package/node_modules/@spectie/adapter/index.mjs

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+
+// Same normalization as the core; handshake checks the resulting manifest exactly.
+export function manifest(url) {
+  let source;
+  try { source = JSON.parse(fs.readFileSync(new URL('./adapter.json', url), 'utf8')); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const pkg = JSON.parse(fs.readFileSync(new URL('./package.json', url), 'utf8'));
+    source = {adapter_id: pkg.name.replace(/^@/, '').replace('/', '.'), ...pkg.spectie, version: pkg.version};
+  }
+  const value = {
+    manifest_schema:'1', category:'language', protocol:'1',
+    entry:['node','{package}/adapter.mjs'], runtime:{name:'node',minimum:'22'},
+    requires:[], parsers:{}, algorithms:['raw-span-v1'], limits:[], ...source,
+  };
+  value.capabilities = value.capabilities.map(cap => ({id:value.adapter_id, phase:'language', requires:[], ...cap}));
+  value.resolution_extensions ??= [...new Set(value.capabilities.flatMap(cap => cap.input_types).filter(t => t !== '*'))];
+  return value;
+}
+
+export function documents(input) {
+  const result = new Map();
+  for (const file of input.files) {
+    const raw = Buffer.from(file.content, 'base64');
+    if (result.has(file.path) || crypto.createHash('sha256').update(raw).digest('hex') !== file.sha256)
+      throw Error('input digest mismatch or duplicate file');
+    let text = null;
+    try { text = new TextDecoder('utf-8', {fatal:true, ignoreBOM:true}).decode(raw); } catch {}
+    result.set(file.path, {...file, raw, text});
+  }
+  return result;
+}
+export function output() { return {facts:[], embeddings:[], diagnostics:[], processed:[]}; }
+export function diagnostic(out, code, path, message) { out.diagnostics.push({code,path,message}); }
+// Indexes live only for this single-request adapter process.
+const byteOffsets = new Map();
+export function span(path, source, start, end, offset=0) {
+  let offsets = byteOffsets.get(source);
+  if (!offsets) {
+    offsets = new Uint32Array(source.length + 1);
+    for (let i = 0; i < source.length; i++) {
+      const code = source.charCodeAt(i), next = source.charCodeAt(i + 1);
+      if (code >= 0xd800 && code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) {
+        offsets[i + 1] = offsets[i] + 3; // A prefix ending inside a pair encodes a replacement character.
+        offsets[i + 2] = offsets[i] + 4;
+        i++;
+      } else offsets[i + 1] = offsets[i] + (code < 0x80 ? 1 : code < 0x800 ? 2 : 3);
+    }
+    byteOffsets.set(source, offsets);
+  }
+  return {path,start:offset+offsets[start],end:offset+offsets[end]};
+}
+
+export async function serve(load, url) {
+  let request, metadata;
+  try {
+    metadata = manifest(url);
+    request = JSON.parse(fs.readFileSync(0, 'utf8'));
+    if (request.protocol_version !== '1' || request.adapter_id !== metadata.adapter_id || request.adapter_version !== metadata.version)
+      throw Error('incompatible request');
+    if (!['handshake','analyze'].includes(request.action) || (request.action === 'handshake' && Object.keys(request.input).length))
+      throw Error('unsupported action or handshake input');
+    if (Number(process.versions.node.split('.')[0]) < 22) throw Error('Node >=22 required');
+    const handler = await load(metadata); // dependency checks also run during handshake
+    const result = request.action === 'handshake' ? metadata : await handler(request.input);
+    const {protocol_version, request_id, adapter_id, adapter_version, input_digest} = request;
+    process.stdout.write(JSON.stringify({protocol_version,request_id,adapter_id,adapter_version,input_digest,
+      status:result.diagnostics?.length?'partial':'complete',result}));
+  } catch (error) {
+    if (!request || !metadata) { process.stderr.write(String(error)); process.exitCode=2; return; }
+    const {protocol_version, request_id, input_digest} = request;
+    process.stdout.write(JSON.stringify({protocol_version,request_id,adapter_id:metadata.adapter_id,adapter_version:metadata.version,input_digest,
+      status:'failure',result:{code:['ERR_MODULE_NOT_FOUND','MODULE_NOT_FOUND'].includes(error.code)?'missing_dependency':'adapter_analysis_failure',message:String(error)}}));
+  }
+}
+
+// The batch interface remains available through serve for cross-file and phased adapters.
+export function language({analyze, offsets='utf16', load=async()=>{}}) {
+  if (!['utf16','bytes'].includes(offsets)) throw Error('offsets must be utf16 or bytes');
+  return async metadata => {
+    await load(metadata);
+    return async input => {
+      const out = output(), docs = documents(input);
+      for (const unit of input.units) {
+        const file = docs.get(unit.path), raw = file.raw.subarray(unit.start, unit.end);
+        let text;
+        try { text = new TextDecoder('utf-8', {fatal:true,ignoreBOM:true}).decode(raw); }
+        catch { diagnostic(out,'unsupported_encoding',unit.path,'Only strict UTF-8 supported'); continue; }
+        const at = (start,end) => {
+          const size = offsets === 'bytes' ? raw.length : text.length;
+          if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || start > end || end > size)
+            throw Error('invalid source range');
+          if (offsets === 'bytes') return {path:unit.path,start:unit.start+start,end:unit.start+end};
+          // Parsers must never split a surrogate pair, even though JS permits slicing one.
+          for (const n of [start,end]) if (n > 0 && /[\uD800-\uDBFF]/.test(text[n-1]) && /[\uDC00-\uDFFF]/.test(text[n] ?? ''))
+            throw Error('range splits a surrogate pair');
+          return span(unit.path,text,start,end,unit.start);
+        };
+        const document = {path:unit.path,text,raw,inputType:unit.input_type,role:unit.role,span:at,
+          symbol:({start,end,algorithm=metadata.algorithms[0],...rest}) => ({...rest,kind:'symbol',...at(start,end),algorithm}),
+          region:({start,end,algorithm=metadata.algorithms[0],...rest}) => ({...rest,kind:'region',...at(start,end),algorithm}),
+          reference:({start,end,...rest}) => ({...rest,kind:'reference',...at(start,end)})};
+        try {
+          const result = await analyze(document, input.config);
+          if (!result || typeof result !== 'object' || Array.isArray(result)) throw Error('return a result object; use {} for a successful empty result');
+          if (Object.keys(result).some(key => !['facts','embeddings','diagnostics','complete'].includes(key))) throw Error('unsupported language result field');
+          for (const key of ['facts','embeddings','diagnostics']) {
+            if (result[key] !== undefined && !Array.isArray(result[key])) throw Error(key+' must be an array');
+          }
+          if (result.complete !== undefined && typeof result.complete !== 'boolean') throw Error('complete must be boolean');
+          for (const key of ['facts','embeddings','diagnostics']) out[key].push(...(result[key] ?? []));
+          if (result.complete !== false) out.processed.push(unit);
+          else diagnostic(out,'partial_parse',unit.path,'Parser did not complete this unit');
+        } catch (error) { diagnostic(out,'parse_error',unit.path,String(error)); }
+      }
+      return out;
+    };
+  };
+}
+export function run(adapter, url) { return serve(adapter, url); }

package/node_modules/@spectie/adapter/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@spectie/adapter",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": "./index.mjs",
+  "files": [
+    "index.mjs"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  }
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@spectie/adapter-javascript",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "adapter.mjs",
+    "adapter.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "typescript": "5.9.3",
+    "@spectie/adapter": "file:../../adapter-runtime/node"
+  },
+  "bundleDependencies": [
+    "@spectie/adapter"
+  ]
+}