@akanjs/language 0.0.0-stage → 3.1.2-rc.1

package/README.ko.md

@@ -0,0 +1,42 @@
+# @akanjs/language
+
+[English](https://github.com/akan-team/akanjs/blob/main/pkgs/@akanjs/language/README.md) | [문서](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/@akanjs/language) | [런타임](https://www.npmjs.com/package/akanjs)
+
+Akan.js 에디터 지원 밑에 있는, 에디터와 무관한 색인입니다.
+
+Akan.js는 원본 키 하나에서 여러 이름을 만듭니다. `memo`의 slice 키 `inPublic`은 `fetch.initMemoInPublic`과
+`st.use.memoListInPublic`이 되고, 필드 `name`은 `st.do.setNameOnMemo`, Filter 쿼리 키 `byName`은 `listByName`이
+됩니다. TypeScript는 이런 이름의 선언을 남기지 않습니다. `@akanjs/language`는 워크스페이스의 constant, document,
+service, signal, store 파일을 문법만으로 읽고, 합성된 이름마다 원본 키를 찾아 줍니다.
+
+에디터 연동용 패키지이며, 앱 코드에서는 import하지 않습니다.
+
+## 설치
+
+```bash
+bun add -d @akanjs/language typescript
+```
+
+## 사용 예시
+
+```ts
+import { AkanIndex } from "@akanjs/language";
+import ts from "typescript";
+
+const index = new AkanIndex({ ts, root: "/path/to/workspace" });
+index.setFile(fileName, text);
+
+index.definitionAt(fileName, text, offset);
+index.hoverAt(fileName, text, offset);
+index.referencesAt(fileName, offset, readText);
+index.sourceKeysOf(fileName);
+index.renameAt(fileName, offset, "inFeed", readText);
+```
+
+호스트가 쓰는 `typescript`를 넘기세요. 이 패키지는 TypeScript를 번들하지 않으며, 사본이 둘이면 `SyntaxKind` 숫자가
+어긋납니다. `apps/**`와 `libs/**`의 TypeScript 파일을 모두 `setFile`로 넣고, 파일이 바뀌면 `setFile`을 다시 부르거나
+`removeFile`을 부르세요. 파일 이름의 구분자는 `\`와 `/` 어느 쪽이든 되고, `readText`에 넘기는 이름과 span의 이름은 `/`를
+씁니다. 이름은 자기 앱과 모든 lib 안에서만 풀리고, 다른 앱으로는 가지 않습니다. `renameAt`은 slice 키나 쿼리 키를, 그
+키에서 만들어진 이름 전부와 모듈 dictionary의 키와 함께 바꾸는 편집을 돌려줍니다.
+
+ES module과 CommonJS로 배포하며, 런타임 의존성은 없습니다.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @akanjs/language
 
-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.
+[한국어](https://github.com/akan-team/akanjs/blob/main/pkgs/@akanjs/language/README.ko.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/@akanjs/language) | [Runtime](https://www.npmjs.com/package/akanjs)
+
+The editor-neutral index behind Akan.js editor support.
+
+Akan.js builds many names from one source key: the slice key `inPublic` on `memo` becomes `fetch.initMemoInPublic`
+and `st.use.memoListInPublic`, a field `name` becomes `st.do.setNameOnMemo`, and a Filter query key `byName` becomes
+`listByName`. TypeScript keeps no declaration for such names. `@akanjs/language` reads a workspace's constant,
+document, service, signal and store files by syntax alone and maps each derived name back to its source key.
+
+It is for editor integrations. Apps never import it.
+
+## Install
+
+```bash
+bun add -d @akanjs/language typescript
+```
+
+## Usage
+
+```ts
+import { AkanIndex } from "@akanjs/language";
+import ts from "typescript";
+
+const index = new AkanIndex({ ts, root: "/path/to/workspace" });
+index.setFile(fileName, text);
+
+index.definitionAt(fileName, text, offset);
+index.hoverAt(fileName, text, offset);
+index.referencesAt(fileName, offset, readText);
+index.sourceKeysOf(fileName);
+index.renameAt(fileName, offset, "inFeed", readText);
+```
+
+Pass the host's own `typescript`: the package bundles none, and two copies would disagree on `SyntaxKind` numbers.
+Feed every `apps/**` and `libs/**` TypeScript file to `setFile`, then call `setFile` again or `removeFile` as files
+change. File names may use either separator; `readText` is called with, and every span carries, forward slashes. A
+name resolves within its own app and every lib, never another app. `renameAt` returns the edits that rename a slice or
+query key together with every name derived from it and its key in the module dictionary.
+
+The package ships as an ES module and as CommonJS, with no runtime dependency.

package/akanIndex.d.ts

@@ -0,0 +1,41 @@
+import { type Ts } from "./ast";
+import { type AkanSpan } from "./moduleFacts";
+import { type AkanFamily, type AkanTarget } from "./nameTable";
+export interface AkanIndexOptions {
+    ts: Ts;
+    root: string;
+}
+export interface AkanHover {
+    name: string;
+    targets: AkanTarget[];
+}
+export interface AkanRenameEdit {
+    span: AkanSpan;
+    newText: string;
+}
+export interface AkanSourceKey {
+    family: AkanFamily;
+    sourceKey: string;
+    label: string;
+    detail: string[];
+    span: AkanSpan;
+}
+export declare class AkanIndex {
+    #private;
+    constructor({ ts, root }: AkanIndexOptions);
+    static isSourcePath(fileName: string): boolean;
+    get fileCount(): number;
+    setFile(givenName: string, text: string): void;
+    removeFile(givenName: string): void;
+    definitionAt(givenName: string, text: string, offset: number): AkanTarget[];
+    hoverAt(givenName: string, text: string, offset: number): AkanHover | null;
+    sourceKeysOf(givenName: string): AkanSourceKey[];
+    sourceKeyAt(givenName: string, offset: number): AkanSourceKey | null;
+    referencesAt(givenName: string, offset: number, readText: (fileName: string) => string | undefined): AkanSpan[];
+    renameTargetAt(givenName: string, offset: number): {
+        family: AkanFamily;
+        sourceKey: string;
+        span: AkanSpan;
+    } | null;
+    renameAt(givenName: string, offset: number, newKey: string, readText: (fileName: string) => string | undefined): AkanRenameEdit[] | null;
+}

package/ast.d.ts

@@ -0,0 +1,16 @@
+import type * as TS from "typescript";
+export type Ts = typeof TS;
+export declare const createAst: (ts: Ts) => {
+    sourceFileFor: (fileName: string, content: string, scriptKind?: TS.ScriptKind) => TS.SourceFile;
+    nodeName: (node: TS.PropertyName | TS.BindingName | undefined) => string | null;
+    propertyName: (node: TS.ObjectLiteralElementLike) => string | null;
+    expressionName: (expression: TS.Expression) => string | null;
+    callExpressionName: (node: TS.CallExpression) => string | null;
+    firstObjectReturnedByArrow: (node: TS.Node) => TS.ObjectLiteralExpression | null;
+    heritageCallNamed: (node: TS.ClassDeclaration, names: ReadonlySet<string>) => {
+        callee: string;
+        call: TS.CallExpression;
+    } | null;
+    heritageCall: (node: TS.ClassDeclaration) => TS.CallExpression | null;
+};
+export type AkanAst = ReturnType<typeof createAst>;