readme

AsterDY · AsterDY · commit b6f1aafd9c61 · 2025-04-19T15:00:44.000+08:00
diff --git a/README.md b/README.md
@@ -18,109 +18,57 @@
 
 ![ABCoder](images/ABCoder.png)
 
-ABCoder, an AI-powered tool, streamlines coding by keeping real-time status updates, providing lossless code compression, and giving development guidance. It enhances testing by identifying quality, generating reports, and auto-creating test cases. It also offers guidance for refactoring, including language stack switches.
-
-# Table of Contents
-
-- [ABCoder: AI-Based Coder(AKA: A Brand-new Coder)](#abcoder-ai-based-coderaka-a-brand-new-coder)
-- [Table of Contents](#table-of-contents)
-- [Overview](#overview)
-- [Quick Start](#quick-start)
-  - [Prerequisites](#prerequisites)
-  - [Running through Coze OpenAPI](#running-through-coze-openapi)
-- [Status Update](#status-update)
-- [Lossless Compression](#lossless-compression)
-- [Development Guide](#development-guide)
-- [Testing Enhancements](#testing-enhancements)
-- [Refactor/Rewrite Guide](#refactorrewrite-guide)
-- [Getting Involved](#getting-involved)
-
-# Overview
-
-ABCoder is a comprehensive open-source software development tool that aims to utilize artificial intelligence to enhance
-the process of coding. This project focuses on various aspects of software development ranging from repository analysis,
-issue and pull request tracking, to automated code compression, development guidance, testing enhancement, and
-refactoring guidance.
-
-# Quick Start
-
-## Prerequisites
-- install git and set your access token for github on cmd-line
-- install [rust-toolchain](https://www.rust-lang.org/tools/install) (stable)
-- (optional) install [ollama](https://github.com/ollama/ollama) and run your LLM
-- (optional) create a [Coze](https://www.coze.com/docs/developer_guides/coze_api_overview?_lang=en) agent and set its OpenAPI key
-
-## Running through Coze OpenAPI
-1. Set .env file for configuration on ABCoder's working directory. Taking Coze as an example:
-```
-# cache for repo，AST and so on
-WORK_DIR=tmp_abcoder
+ABCoder, an AI-oriented code handling tool, is designed to enhance coding-context for Large-Language-Model (LLM).
 
-# exclude dirs for repo parsing, separated by comma
-EXCLUDE_DIRS=target,gen-codes 
 
-# LLM's api type
-API_TYPE=coze # coze|ollama 
+## Features
 
-# LLM's output language
-LANGUAGE=zh 
+-  Universal Abstract Syntax Tree (UniAST), an language-independent and AI-friendly  coding-context, provides ample and recursive code information for AI or programs.
+  
+-  Universal Parser, parses abitary languages to UniAST.
 
-# Coze options
-COZE_API_TOKEN="{YOUR_COZE_API_TOKEN}"
-COZE_BOT_ID={YOUR_COZE_BOT_ID}
-```
+-  Univeral Writer, transforms UniAST back to codes.
 
-2. compile the parsers
-```
-./script/make_parser.sh
-```
+- (WIP) Code Understanding and Semantic Querying, which can be used to retrieve codes with natural language for either human or AI.
+  
+Based on these features, ABCoder can help developers to easily implement or enhance many AI-assisted coding applications, such as code reviewer, IDE copilot and so on.
 
-3. compile and run ABCoder
-```
-cargo run --bin cmd compress https://xxx.git
-```
+## Getting Started
 
-4. Once triggered, ABCoder will take three steps:
-   1. Download the repository in {REPO_DIR}
-   2. Parse the repository and store the AST in {CACHE_DIR}
-   3. Call the LLM to compress the repository codes, and refresh the AST for each call.
-You can stop the process at anytime after step 2. You can restart the compressing by running the same command.
-
-5. Export the compressed results
+1. Install ABCoder:
+```bash
+go install github.com/cloudwego/abcoder@latest
 ```
-cargo run --bin cmd export https://xxx.git --out-dir {OUTPUT_DIR}
+2. Use ABCoder to parse a repository to UniAST (JSON)
+```bash
+abcoder parse <language> <repo-path> > <AST-path>
+```
+3. Use ABCoder as a writer
+```bash
+abcoder write <AST-path>
 ```
 
-# Status Update
-
-The system is designed to automatically fetch the latest data from Github upon triggering relevant tasks, ensuring the
-repository status is always up-to-date. It can answer queries related to function, defects based on issue and PR
-information. For more details, check out our Issues and Pull Requests sections on Github.
-
-# Lossless Compression
-
-The system also offers a lossless compression feature for repository code. The specific implementation methods are being
-optimized, and more details will be available soon.
+## Universal-Abstract-Syntax-Tree Specification
 
-# Development Guide
+see [UniAST Specification](docs/uniast-zh.md)
 
-We welcome all developers wishing to contribute to ABCoder. Our system provides detailed guidance for manual development
-and also supports auto-generation of instructions. Check out our Contribution Guide for more information.
 
-# Testing Enhancements
+## Supported Languages
 
-The system is designed to analyze existing functions and corresponding tests, identify the overall quality of testing,
-produce reports, and automatically generate test cases for weakly covered items. Our goal is to help repositories
-enhance and perfect their test cases.
+ABCoder currently supports the following languages:
 
-# Refactor/Rewrite Guide
+| Language | Parser | Writer |
+| -------- | ------ | ------ |
+| Go       | ✅      | ✅      |
+| Rust     | ✅      | WIP    |
+| C        | WIP    | ❌      |
 
-We offer guidance for both small-scale feature iterations and large-scale rewrites, including language stack switches.
-Our system provides a detailed guide for manual development and also supports automated guidance generation.
 
-# Getting Involved
+## Getting Involved
 
 We encourage developers to contribute and make this tool more powerful. If you are interested in contributing to ABCoder
-project, kindly check out our Getting Involved Guide.
+project, kindly check out our Getting Involved Guide:
+- [Parser Extension](docs/parser_extension-zh.md)
+- [Writer Extension](docs/writer_extension-zh.md)
 
 > Note: This is a dynamic README and is subject to changes as the project evolves.
diff --git a/docs/uniast-zh.md b/docs/uniast-zh.md
@@ -0,0 +1,16 @@
+<!--
+ Copyright 2025 ByteDance Inc.
+ 
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ 
+     https://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
diff --git a/lang/uniast/ast.go b/lang/uniast/ast.go
@@ -47,11 +47,15 @@ func NewLanguage(lang string) (l Language) {
 	}
 }
 
+// Node ID (string) => Node
+// Node ID comes from Identity.Full()
+type NodeGraph map[string]*Node
+
 // Repository
 type Repository struct {
 	Name    string             `json:"id"` // module name
-	Modules map[string]*Module // module name => Library
-	Graph   map[string]*Node
+	Modules map[string]*Module // module name => module
+	Graph   NodeGraph          // node id => node
 }
 
 func (r Repository) ID() string {
@@ -223,12 +227,16 @@ func ModPathName(mod ModPath) string {
 	return mod
 }
 
-// Identity holds identity information about a third party declaration
+// Identity is the universal-unique for an ast node.
 type Identity struct {
-	ModPath `json:"ModPath" jsonschema:"description=the compiling module of the ast node, the format is {ModName} or {ModName}@{Version}"` // ModPath is the module which the package belongs to
-	PkgPath `json:"PkgPath" jsonschema:"description=the namespace of the ast node"`                                                        // Import Path of the third party package
+	// module id, must be unique within a repo
+	ModPath `json:"ModPath" jsonschema:"description=the compiling module of the ast node, the format is {ModName} or {ModName}@{Version}"`
+
+	// path id, must be unique within a module
+	PkgPath `json:"PkgPath" jsonschema:"description=the namespace of the ast node"`
 
-	Name string `json:"Name" jsonschema:"description=unique name of the ast node, the format is one of {FunctionName}, {TypeName}.{MethodName}, {InterfaceName}<{TypeName}>.{MethodName}, {TypeName}"` // Unique Name of declaration (FunctionName, TypeName.MethodName, InterfaceName<TypeName>.MethodName, or TypeName)
+	// symbol id , must be unique within a package
+	Name string `json:"Name" jsonschema:"description=unique name of the ast node, the format is one of {FunctionName}, {TypeName}.{MethodName}, {InterfaceName}<{TypeName}>.{MethodName}, {TypeName}"`
 }
 
 func NewIdentity(mod, pkg, name string) Identity {
diff --git a/lang/uniast/node.go b/lang/uniast/node.go
@@ -201,13 +201,16 @@ type Relation struct {
 // 	return json.Marshal(rr)
 // }
 
-// Node 类型
+// Node Type
 type NodeType int
 
 const (
 	UNKNOWN NodeType = iota
+	// top Function、 methods
 	FUNC
+	// Struct、TypeAlias、Enum...
 	TYPE
+	// Global Varable or Global Const
 	VAR
 )
 
@@ -251,12 +254,18 @@ func NewNodeType(typ string) NodeType {
 	}
 }
 
+// an Entity in a language
 type Node struct {
+	// unique identity of the node
 	Identity
-	Type         NodeType
+	// Node Type, must be one of FUNC, TYPE, VAR
+	Type NodeType
+	// other nodes that  depends on this node
 	Dependencies []Relation
-	References   []Relation
-	Repo         *Repository `json:"-"`
+	// other nodes that reference this node
+	References []Relation
+	// the repo that this node belongs to
+	Repo *Repository `json:"-"`
 }
 
 func (n Node) GetDependency(id Identity) *Relation {
