From 6a3c96297d08a61d9cc53ccd62524c09ae8fe03b Mon Sep 17 00:00:00 2001 From: ximengkai Date: Sat, 5 Sep 2026 00:22:49 +0800 Subject: [PATCH] docs(objective-c): integrate provider documentation --- AGENTS.md | 2 +- ARCHITECTURE.md | 5 +- README.md | 5 +- docs/fork/README.md | 46 ------------------- .../objective-c-provider.md} | 15 +++--- 5 files changed, 12 insertions(+), 61 deletions(-) delete mode 100644 docs/fork/README.md rename docs/{fork/OBJECTIVE_C_PROVIDER.md => languages/objective-c-provider.md} (93%) diff --git a/AGENTS.md b/AGENTS.md index 1492a30e9..2c49ab489 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING. ## Reference docs - **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)** -- **Fork-specific work:** read **[docs/fork/README.md](docs/fork/README.md)** before changing the Objective-C provider. This document defines the fork contract; ForgeMate runner and version orchestration remain outside this repository. +- **Objective-C provider work:** read **[docs/languages/objective-c-provider.md](docs/languages/objective-c-provider.md)** before changing Objective-C parsing or resolution. - **Call & inheritance resolution (RFC #909 Ring 3):** See ARCHITECTURE.md § Scope-Resolution Pipeline. All languages resolve calls and inheritance through the scope-resolution pipeline (`Registry.lookup`, `preEmitInheritanceEdges`, `emitHeritageEdges`, `buildMro` → `MethodDispatchIndex`). **Shared code in `gitnexus/src/core/ingestion/` must not name languages** — plug language behavior in via `LanguageProvider` / `ScopeResolver` hooks. A language plugs in by implementing `ScopeResolver` (`scope-resolution/contract/scope-resolver.ts`) and registering it in `SCOPE_RESOLVERS`. (The legacy call-resolution DAG + `@heritage` capture path were removed in RING4-1 #942.) - **Cursor:** `.cursor/index.mdc` (always-on); `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` deprecated. - **GitNexus:** standard skills in `.claude/skills/gitnexus-*/`; MCP rules in `gitnexus:start` block below. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index b1076d1d5..a1d2589bb 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -377,7 +377,7 @@ CI auto-discovers the set via `tsx`. No workflow edit required. ## Language-agnostic graph feeding -16 languages → single unified graph. Four abstraction layers: +18 languages → single unified graph. Four abstraction layers: ``` Unified Graph Schema (44 node types, 21 relationship types) @@ -405,7 +405,7 @@ Each language implements `LanguageProvider` (`language-provider.ts`). Key fields | `descriptionExtractor` | Optional hook returning a symbol's doc-comment text as its `description`; feeds the embedding metadata header so doc-only terms are semantically searchable (issue #2270). Most languages register `createLeadingDocDescriptionExtractor` (shared, language-neutral; per-language comment/wrapper config passed at the call site) | | `definitionPropertiesExtractor` | Optional language-owned hook for structured, clone-safe definition metadata. Shared ingestion persists these properties opaquely; the owning provider supplies the extraction semantics. | -16 providers in `languages/index.ts` via `satisfies Record` — missing a language is a compile error. +18 providers in `languages/index.ts` via `satisfies Record` — missing a language is a compile error. ### Unified capture tags @@ -542,4 +542,5 @@ Node IDs use arity suffix (`#`): `Method:file:Class.method#1` vs `#2 - [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery - [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents - [TESTING.md](TESTING.md) — how to run tests +- [docs/languages/objective-c-provider.md](docs/languages/objective-c-provider.md) — Objective-C provider behavior and limits - `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage diff --git a/README.md b/README.md index d0ed86f84..9e92ca1e4 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,6 @@ npx gitnexus setup That's it. `analyze` indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command. `setup` writes the MCP config so your AI agent can use the graph. -## ForgeMate Fork Extension - -This fork keeps upstream GitNexus behavior as the default. Objective-C semantic indexing is implemented as an MVP on the fork's `objective-c_support` branch; it is not part of upstream `main` or the published upstream package. Its compatibility requirements and acceptance criteria live in [docs/fork/README.md](docs/fork/README.md). -
Install problems? npm 11 crash · slow cold install · no C++ toolchain @@ -661,6 +657,7 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas | Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ | | C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | +| Objective-C | ✓ | — | ✓ | ✓ | ✓ | — | — | — | — | | Dart | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | | Zig | ✓ | — | ✓ | — | ✓ | ✓ | ✓ | — | ✓ | diff --git a/docs/fork/README.md b/docs/fork/README.md deleted file mode 100644 index 5f801e9ad..000000000 --- a/docs/fork/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Forge-Specific Extensions - -Status: planning baseline - -This directory records behavior that belongs to the `mengkaka/GitNexus` fork. It is intentionally separate from upstream-oriented architecture and user documentation so that a future rebase can distinguish fork contracts from upstream behavior. - -## Baseline and status - -- Upstream project: -- Fork remote: -- Current fork revision when this directory was introduced: `28187bb3a708` -- Public compatibility rule: without a documented fork option, GitNexus must preserve upstream behavior. - -| Capability | Status | Contract | -| --- | --- | --- | -| Objective-C Provider | Implemented | [OBJECTIVE_C_PROVIDER.md](OBJECTIVE_C_PROVIDER.md) | - -`Implemented` means the documented MVP, regression tests, metadata contract, and package/runtime wiring are present on the fork's `objective-c_support` branch. It does not expand the provider into full Objective-C runtime dispatch. Each implementation PR must update this table, its related design document, and tests. - -## Reading order - -1. Read this file for scope and compatibility boundaries. -2. Read [OBJECTIVE_C_PROVIDER.md](OBJECTIVE_C_PROVIDER.md) before adding Objective-C parsing or resolution. -3. Read `ARCHITECTURE.md`, `AGENTS.md`, and the affected implementation code before editing. - -## Ownership boundary - -GitNexus fork responsibilities: - -- Parse and model Objective-C with explicit confidence and unresolved cases. - -ForgeMate responsibilities, intentionally not implemented here: - -- Repository lifecycle, source SHA selection, Wiki publication, job status, access control, and cross-repository authorization. -- Combining Wiki and code evidence in its own MCP facade. - -The fork must not turn GitNexus into ForgeMate's authoritative version database or a multi-repository shared graph database. A GitNexus index remains a rebuildable per-repository artifact. - -## Change rules - -- Keep default, no-option behavior byte-for-byte compatible where practical. -- Do not add ForgeMate-specific paths, project IDs, credentials, or runner behavior to GitNexus core. - -## Documentation lifecycle - -The local `docs/plans/` files are working notes and may remain ignored. Once a design is adopted, this directory is the tracked source of truth for fork contracts. User-facing documentation must not advertise a planned option as available before its code and regression tests land. diff --git a/docs/fork/OBJECTIVE_C_PROVIDER.md b/docs/languages/objective-c-provider.md similarity index 93% rename from docs/fork/OBJECTIVE_C_PROVIDER.md rename to docs/languages/objective-c-provider.md index 69f038678..f2b243ded 100644 --- a/docs/fork/OBJECTIVE_C_PROVIDER.md +++ b/docs/languages/objective-c-provider.md @@ -1,12 +1,11 @@ -# Objective-C Provider +# Objective-C Language Provider Status: implemented -Implementation note (`dev` branch): the first deterministic provider is wired in and covered by -focused unit/integration tests. The parser-loader ABI smoke runs in the published multi-OS test -matrix, and the native prebuild workflow owns Objective-C together with all six vendored grammar -targets. This status describes the implemented MVP; it does not promise full Objective-C -runtime dispatch. +The deterministic provider is covered by focused unit and integration tests. The parser-loader ABI +smoke runs in the published multi-OS test matrix, and the native prebuild workflow owns +Objective-C together with all six vendored grammar targets. This status describes the implemented +MVP; it does not promise full Objective-C runtime dispatch. ## Goal @@ -89,9 +88,9 @@ The acceptance bar is: The MVP does not promise exact runtime type inference for `id` or `instancetype`, reflection, swizzling, arbitrary category replacement, dynamic selector construction, or complete impact analysis across every runtime dispatch path. Tool results must surface confidence and unresolved evidence rather than presenting guesses as certain graph facts. -## Current implementation coverage on `dev` +## Current implementation coverage -Implemented in the branch: +Implemented capabilities: - Vendored `tree-sitter-objc` grammar, registered through the existing Tree-sitter loader. - `.m` and `.mm` language mapping plus content-based `.h` classification so plain C/C++ headers are not unconditionally claimed.