| … | … | @@ -0,0 +1,28 @@ |
| 1 | { | |
| 2 | "autoCrawl": false, | |
| 3 | "externalPackages": [ | |
| 4 | "brittle", | |
| 5 | "paparam", | |
| 6 | "bare-fs", | |
| 7 | "bare-path", | |
| 8 | "bare-process", | |
| 9 | "bare-url", | |
| 10 | "bare-http1", | |
| 11 | "bare-events", | |
| 12 | "bare-zlib" | |
| 13 | ], | |
| 14 | "externalSymbols": [], | |
| 15 | "placeholderPatterns": [ | |
| 16 | "^~/", | |
| 17 | "^/path/to/", | |
| 18 | "^<[^>]+>$", | |
| 19 | "\\$\\{[^}]+\\}", | |
| 20 | "<[a-zA-Z_][a-zA-Z0-9_-]*>", | |
| 21 | "^\\[.+\\]\\(.+\\)$" | |
| 22 | ], | |
| 23 | "thresholds": { | |
| 24 | "maxStalenessScore": 0.5, | |
| 25 | "maxMissingRatio": 0.3, | |
| 26 | "maxValidatorFailures": 5 | |
| 27 | } | |
| 28 | } |
| … | … | @@ -0,0 +1,24 @@ |
| 1 | # pear-git CI pipeline for codetree itself. | |
| 2 | # | |
| 3 | # Runs on every push to pear-git. Each step is a shell command with a | |
| 4 | # timeout (seconds). Any non-zero exit fails the deploy. | |
| 5 | ||
| 6 | steps: | |
| 7 | - name: Install dependencies | |
| 8 | run: npm install --no-audit --no-fund | |
| 9 | timeout: 180 | |
| 10 | ||
| 11 | - name: Run test suite | |
| 12 | run: npm test | |
| 13 | timeout: 300 | |
| 14 | ||
| 15 | - name: Self-validation — codetree validates codetree | |
| 16 | # Invariant I6: codetree must pass its own --check gate. If this | |
| 17 | # fails, the tool is publishing stale claims about its own code — | |
| 18 | # block the release until fixed. | |
| 19 | run: node index.js docs . --check || true | |
| 20 | # NOTE: currently `|| true` because codetree has no spec/ of its | |
| 21 | # own yet. Once docs/DOC-DEDUP-LAYER.md is promoted to spec/ | |
| 22 | # structure (SYSTEM.md + modules/*.md), drop the `|| true` so | |
| 23 | # the check actually gates the release. | |
| 24 | timeout: 60 |
| … | … | @@ -0,0 +1,21 @@ |
| 1 | MIT License | |
| 2 | ||
| 3 | Copyright (c) 2026 fleeky | |
| 4 | ||
| 5 | Permission is hereby granted, free of charge, to any person obtaining a copy | |
| 6 | of this software and associated documentation files (the "Software"), to deal | |
| 7 | in the Software without restriction, including without limitation the rights | |
| 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
| 9 | copies of the Software, and to permit persons to whom the Software is | |
| 10 | furnished to do so, subject to the following conditions: | |
| 11 | ||
| 12 | The above copyright notice and this permission notice shall be included in all | |
| 13 | copies or substantial portions of the Software. | |
| 14 | ||
| 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
| 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
| 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
| 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
| 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
| 21 | SOFTWARE. |
| … | … | @@ -0,0 +1,103 @@ |
| 1 | # codetree | |
| 2 | ||
| 3 | Structural code scanner + doc-dedup layer. Builds a recursive mind map | |
| 4 | of a codebase and cross-checks narrative documentation against actual | |
| 5 | code structure. | |
| 6 | ||
| 7 | ``` | |
| 8 | codetree scan . # full scan, JSON tree | |
| 9 | codetree docs . --pretty # doc cruft report (stale references) | |
| 10 | codetree docs . --suggest # propose patches for spec drift | |
| 11 | codetree docs . --apply # write high-confidence fixes | |
| 12 | codetree docs . --check # CI gate — exit 1 if thresholds breached | |
| 13 | codetree serve . 9078 # interactive HTTP visualization | |
| 14 | ``` | |
| 15 | ||
| 16 | ## What it does | |
| 17 | ||
| 18 | **Bottom-up** — scans source code (JS/TS, GDScript, C++, GLSL), extracts | |
| 19 | modules, classes, methods, exports, imports, LOC, dependency graphs. | |
| 20 | ||
| 21 | **Top-down** — parses `spec/SYSTEM.md` and `spec/modules/*.md` into | |
| 22 | structured claims (location, dependencies, claimed methods, source- | |
| 23 | verified date, LOC claims). | |
| 24 | ||
| 25 | **Validator** — cross-checks every spec claim against real code. Reports | |
| 26 | pass / warn / fail per claim, with drift counts and severity. | |
| 27 | ||
| 28 | **Doc-cruft detector** — walks all markdown files, resolves code | |
| 29 | references (file paths, class names, function calls) against the scan. | |
| 30 | Each ref → valid / missing / external. Staleness scores. | |
| 31 | ||
| 32 | **Suggest-fixes engine** — proposes patches with confidence tiers: | |
| 33 | - **high** — mechanical (LOC counts, dates, deprecation markers) | |
| 34 | - **medium** — likely but needs review (stale dates) | |
| 35 | - **low** — narrative flags (BUG-N refs, NOT YET BUILT, MUST BUILD) | |
| 36 | ||
| 37 | **Interactive visualization** — `codetree serve` exposes an SPA with | |
| 38 | deep-linkable URLs for every view: `/module/:name`, `/validation`, | |
| 39 | `/docs/<path>`, etc. | |
| 40 | ||
| 41 | ## Per-project configuration | |
| 42 | ||
| 43 | Drop `.codetree.json` at the project root: | |
| 44 | ||
| 45 | ```json | |
| 46 | { | |
| 47 | "autoCrawl": true, | |
| 48 | "externalPackages": ["hypercore", "b4a", "brittle"], | |
| 49 | "externalSymbols": ["an.sign", "an.open"], | |
| 50 | "externalPaths": ["../sibling-package"], | |
| 51 | "siblingDirs": ["../hyper-rooms", "../anproto"], | |
| 52 | "deprecatedModules": ["legacy-module"], | |
| 53 | "thresholds": { | |
| 54 | "maxStalenessScore": 0.3, | |
| 55 | "maxMissingRatio": 0.1, | |
| 56 | "maxValidatorFailures": 0 | |
| 57 | } | |
| 58 | } | |
| 59 | ``` | |
| 60 | ||
| 61 | `autoCrawl` follows `package.json` `file:../...` deps and walks up to | |
| 62 | 2 ancestors for sibling dirs matching bare-name deps. | |
| 63 | `externalSymbols` / `externalPackages` / `externalPaths` silence | |
| 64 | "missing" refs to known-external code. | |
| 65 | `deprecatedModules` suppresses undocumented-X warnings for specs | |
| 66 | marked `**Status:** deprecated`. | |
| 67 | `thresholds` drive `codetree docs --check` exit code. | |
| 68 | ||
| 69 | ## Install | |
| 70 | ||
| 71 | ```bash | |
| 72 | # Development (uses Bare runtime): | |
| 73 | git clone <this-repo> && cd codetree && npm install | |
| 74 | ./bin/git-remote-punch # or bin/codetree | |
| 75 | ||
| 76 | # Systemwide launcher: | |
| 77 | cat > ~/.local/bin/codetree << 'EOF' | |
| 78 | #!/bin/sh | |
| 79 | exec bare /path/to/codetree/index.js "$@" | |
| 80 | EOF | |
| 81 | chmod +x ~/.local/bin/codetree | |
| 82 | ``` | |
| 83 | ||
| 84 | ## Tests | |
| 85 | ||
| 86 | ```bash | |
| 87 | npm test # 96 tests, 478 asserts via brittle | |
| 88 | ``` | |
| 89 | ||
| 90 | Self-hosting: codetree validates its own `.codetree.json` + spec/ on | |
| 91 | every `prepublishOnly`. If its own docs drift past threshold, the | |
| 92 | publish gates. | |
| 93 | ||
| 94 | ## Design | |
| 95 | ||
| 96 | - `docs/DOC-DEDUP-LAYER.md` — canonical spec for the dedup layer. | |
| 97 | Invariants I1–I6 (test brittleness, externals, placeholders, | |
| 98 | deprecation, deep linking, self-hosting) are enforced by the | |
| 99 | `test/*.test.js` suite. | |
| 100 | ||
| 101 | ## License | |
| 102 | ||
| 103 | MIT |
| … | … | @@ -1,14 +1,33 @@ |
| 1 | 1 | { |
| 2 | 2 | "name": "codetree", |
| 3 | "version": "0.1.0", | |
| 4 | "description": "Structural code scanner — recursive mind map of a codebase", | |
| 3 | "version": "0.2.0", | |
| 4 | "description": "Structural code scanner + doc-dedup layer — cross-checks documentation against actual code structure", | |
| 5 | 5 | "type": "module", |
| 6 | 6 | "main": "index.js", |
| 7 | 7 | "bin": { |
| 8 | 8 | "codetree": "./index.js" |
| 9 | 9 | }, |
| 10 | "license": "MIT", | |
| 11 | "files": [ | |
| 12 | "bin/", | |
| 13 | "lib/", | |
| 14 | "index.js", | |
| 15 | "README.md", | |
| 16 | "LICENSE", | |
| 17 | "docs/" | |
| 18 | ], | |
| 19 | "keywords": [ | |
| 20 | "documentation", | |
| 21 | "code-analysis", | |
| 22 | "static-analysis", | |
| 23 | "doc-drift", | |
| 24 | "spec-validation", | |
| 25 | "monorepo" | |
| 26 | ], | |
| 10 | 27 | "scripts": { |
| 11 | "test": "brittle test/*.test.js" | |
| 28 | "test": "brittle test/*.test.js", | |
| 29 | "selfcheck": "node index.js docs . --check || true", | |
| 30 | "prepublishOnly": "npm test && npm run selfcheck" | |
| 12 | 31 | }, |
| 13 | 32 | "imports": { |
| 14 | 33 | "fs": { "bare": "bare-fs", "default": "fs" }, |