@fadhilp/lantern 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FadhilP
+
+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/bin/binary.js

@@ -0,0 +1,25 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { platform, arch } = process;
+
+/** Platform directory names to try, best first. A static musl binary also runs on glibc. */
+function candidates() {
+  const base = `${platform}-${arch}`;
+  if (platform === "win32") return [`${base}-msvc`];
+  if (platform !== "linux") return [base];
+  const glibc = process.report?.getReport?.().header?.glibcVersionRuntime;
+  return glibc ? [`${base}-gnu`, `${base}-musl`] : [`${base}-musl`];
+}
+
+// The package holds one directory per platform next to this file.
+function findBinary() {
+  const exe = platform === "win32" ? "lantern.exe" : "lantern";
+  return candidates()
+    .map((directory) => path.join(__dirname, directory, exe))
+    .find((binary) => fs.existsSync(binary));
+}
+
+module.exports = { findBinary };

package/bin/lantern.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { findBinary } = require("./binary.js");
+
+const binary = findBinary();
+if (!binary) {
+  console.error(
+    `lantern: no prebuilt binary for ${process.platform}-${process.arch}; ` +
+      "install from source with `cargo install --git https://github.com/FadhilP/lantern lantern-cli`",
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+  console.error(`lantern: ${result.error.message}`);
+  process.exit(1);
+}
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+process.exit(result.status ?? 1);

package/bin/postinstall.js

@@ -0,0 +1,61 @@
+"use strict";
+
+// On a global npm install, npm's `lantern` command starts Node, which then starts the binary.
+// This script points the command at the binary. If it does nothing or fails, bin/lantern.js still works.
+const fs = require("node:fs");
+const path = require("node:path");
+const { findBinary } = require("./binary.js");
+
+function relinkUnix(prefix, binary) {
+  // The binary path is a real path, so the link directory must be one too, or the relative link is wrong.
+  const directory = fs.realpathSync(path.join(prefix, "bin"));
+  const link = path.join(directory, "lantern");
+  if (!fs.lstatSync(link).isSymbolicLink()) return;
+  const replacement = `${link}.${process.pid}.tmp`;
+  fs.symlinkSync(path.relative(directory, fs.realpathSync(binary)), replacement);
+  // A rename replaces the old link in one step, so the command never goes missing.
+  fs.renameSync(replacement, link);
+}
+
+function rewriteWindowsShims(prefix, binary) {
+  if (!fs.existsSync(path.join(prefix, "lantern.cmd"))) return;
+  const relative = path.relative(prefix, binary);
+  const posixRelative = relative.replaceAll("\\", "/");
+  // npm reads the target back from these files to check that they belong to this package
+  // (read-cmd-shim), so each keeps the shape npm writes: "%~dp0\<path>" %*, "$basedir/<path>" $args,
+  // and "$basedir/<path>" "$@".
+  const shims = {
+    "lantern.cmd": `@ECHO off\r\n"%~dp0\\${relative}" %*\r\n`,
+    // A script in a pipeline gets the piped text in $input; the binary needs it on stdin.
+    "lantern.ps1": [
+      "#!/usr/bin/env pwsh",
+      "$basedir = Split-Path $MyInvocation.MyCommand.Definition -Parent",
+      `if ($MyInvocation.ExpectingInput) { $input | & "$basedir/${posixRelative}" $args } else { & "$basedir/${posixRelative}" $args }`,
+      "exit $LASTEXITCODE",
+      "",
+    ].join("\r\n"),
+    // Git Bash and MSYS run this file, not lantern.cmd. ${0%/*} avoids a dirname process, which is slow on Windows.
+    lantern: [
+      "#!/bin/sh",
+      'case "$0" in */*) basedir="${0%/*}" ;; *) basedir=. ;; esac',
+      `exec "$basedir/${posixRelative}" "$@"`,
+      "",
+    ].join("\n"),
+  };
+  for (const [name, content] of Object.entries(shims)) {
+    fs.writeFileSync(path.join(prefix, name), content);
+  }
+}
+
+const prefix = process.env.npm_config_global_prefix;
+const binary = findBinary();
+const globalNpmInstall = process.env.npm_config_global === "true" && Boolean(prefix);
+
+if (globalNpmInstall && binary) {
+  try {
+    if (process.platform === "win32") rewriteWindowsShims(prefix, binary);
+    else relinkUnix(prefix, binary);
+  } catch (error) {
+    console.error(`lantern: the command will start through Node (${error.message}).`);
+  }
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@fadhilp/lantern",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Read-only code discovery for large codebases",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FadhilP/lantern.git"
+  },
+  "bin": {
+    "lantern": "bin/lantern.js"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "scripts": {
+    "postinstall": "node bin/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/lantern/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: lantern
+description: Find code fast in large repositories with the `lantern` CLI. Use it to find where a symbol is defined, where text or a regex occurs, who references a name, what calls a function or what it calls, and what a file contains. Prefer it over grep or reading whole files when you explore unfamiliar code, trace a call path, or need results that fit a small output budget.
+---
+
+# Lantern
+
+`lantern` is a read-only code index. It never writes inside the repository. Every query refreshes the index first (only changed files are read), so results match the disk.
+
+## Pick the command
+
+| Question | Command |
+|---|---|
+| Where is `X` defined? (instead of `grep -r "class X"`) | `lantern symbols X` (add `--kind class`) |
+| What is the source of `X`? | `lantern symbols X --body` |
+| Where does this text or pattern occur? | `lantern code "text"` or `lantern code "re" --regex` |
+| Who uses `X`? | `lantern refs X` |
+| What calls `X`, and what does `X` call? | `lantern graph X` |
+| What is in this file? | `lantern outline path/to/file` |
+| Is this repository indexed, and how big is it? | `lantern status` |
+
+Lantern has no file-name search. To find a file by name, use your file-glob tool or `git ls-files '*name*'`.
+
+Pick by what you search for:
+
+- **A function, method, class, or type:** use `symbols`, `refs`, or `graph`. They skip comments and strings and name the enclosing definition.
+- **A field or object key** (`row.technician_id`, `{ cedex: ... }`), or text that is not a name (strings, comments, config, SQL, docs): use `code`. `refs` does not record field or property uses.
+- **To read a definition:** use `symbols X --body`. It prints the found definitions with their source lines, so you do not need a separate read.
+- **Before you read a file:** run `outline`, then read only the line range you need. Do not `cat` a whole file or read a large `sed -n 1,200p` range.
+- **To read around a match:** use `code --context N`. You do not need a separate read.
+
+Run the command from inside the repository, or pass `-C <dir>`. `-C` takes a directory, not a context count; for context lines use `--context N`. The first query on a new repository builds the index; later queries are fast. You do not need to run `lantern index` first.
+
+**Several queries in a row:** each query refreshes the index first (about 0.2 s on a large repository). When you chain queries and the files do not change between them, add `--stale-ok` to every query after the first: `lantern symbols A; lantern refs A --stale-ok`. Before a loop, run `lantern index > /dev/null` once, then use `--stale-ok` on every query in the loop. On a repository that was never indexed, `--stale-ok` exits 1.
+
+## Read the output
+
+The default output is compact text, made for agents. Paths are relative to the current directory (`../` for a file outside it), so you can pass a printed path to `--path` or `outline` from the same directory. Lines are 1-based.
+
+- `symbols`: `path:line-end_line kind[ in Container]: signature`, one per line. With `--body`, `line:text` source lines follow each definition, then `-- body cut: N more lines` when it is longer than 100 lines.
+- `code`: a heading line with the file path (`path (N matches, M shown)` when `--per-file` cut matches), then `line:text` for each match and `line-text` for `--context` lines.
+- `refs`: a heading line with the file path, then `line kind[ in Container.name]: text` for each reference.
+- `outline`: `line-end_line kind name`, indented two spaces per nesting level.
+- `graph`: one line per node, `id kind Container.name path:line`, with roots marked `(root)`. Then one line per edge, `from -> to kind at line N`, where line N is in the file of the `from` node. Then `unresolved: ...`.
+- `no results` means nothing matched. After `symbols`, `refs`, or `graph`, a hint gives the `lantern code` command to search for the name as text. Run it when the name can be a field, a key, or a string. After `symbols Container.name`, when other containers define the name, the hint lists them; query again with one of them. After a literal `code` search, a hint says when the pattern has regex syntax (`a|b`, `getStats\(`): run it again with `--regex`. After `outline`, a hint means no parser covers the file type (CSS, HTML); use `lantern code` with `--path` for that file. If the hint says parsing ran out of time, symbols can be missing: run `lantern index --rebuild`, then query again. With `--json`, an empty page or graph carries the hint in a `hint` field. When results look incomplete, check `unparsed_files` in `lantern status`.
+- A last line `-- more: --cursor <value>` means more rows exist. `-- truncated` on a graph means `--max-nodes` or `--max-bytes` cut it.
+
+For the next page, run the same command with `--cursor <value>`. `index`, `status`, and `prune` print a JSON report.
+
+Add `--json` only when a program parses the output. Each command then prints one JSON document; null fields and `truncated: false` are left out. List pages are `{"schema":1,"freshness","indexed_at","truncated"?,"next_cursor"?,"hint"?,"results":[...]}`. Rows:
+- `symbols`: `name, kind, container?, path, line, end_line, signature, body?: {line, text}`.
+- `code`: `path, match_count, matches: [{line, column, text, before?, after?}]`.
+- `refs`: `path, line, column, kind, text, enclosing?: {name, container?, kind}`.
+- `outline`: top-level symbols with nested `children`; the page also has `path` and `language`.
+- `graph`: `roots`, `nodes: [{id, name, container?, kind, path, line}]`, `edges: [{from, to, kind, line}]`, `truncated?`, `unresolved?`.
+
+## Keep output small
+
+- `--limit N` sets rows per page. Defaults: 30 (`code`: 10 files). Max 10 000.
+- `--max-bytes N` cuts the page until the output fits in N bytes (accepts `K`/`M`). Cut rows come back on the next page. If not even one row fits, the command exits 2; raise the value.
+- `--path GLOB` narrows by path, relative to the current directory. Repeat it to match any of several globs (`--path 'src/**' --path 'lib/**'`). A glob without `/` matches at any depth (`*.ts`); with `/` it is anchored (`src/**/*.ts`).
+- `--language L` (for `symbols` and `code`): `c cpp csharp dart go java javascript php python ruby rust typescript tsx`. `typescript` also selects `tsx`. `javascript` includes `.jsx` files.
+- `code --per-file N` caps matches per file (default 20); `match_count` still counts all of them. `code --context N` adds up to N lines around each match (at most 50).
+- `symbols --body` drops the default `--limit` to 5. Each body has at most 100 lines. A body starts at the first decorator, attribute, annotation, or doc comment right before the definition (a blank line ends them), so it can start before the row's `line`.
+- `graph --depth N` (1–3, default 1) and `--max-nodes N` (default 200) bound the graph.
+
+## Command notes
+
+- **symbols**: matches by exact name, prefix, initials, or substring (3 characters or more); letters with gaps between them do not match. Ranks exact name, then case-insensitive exact, then prefix, then initials (`gubi` finds `getUserById`), then substring. Narrow with `--kind function|method|class|interface|struct|enum|trait|type|module|constant|variable|field`. Qualify with a container: `UserStore.getUserById` or `Store::get`.
+- **code**: literal and case-insensitive by default. For a pattern that starts with `-`, use `-e`: `lantern code -e "--flag"`. Add `--regex` for a Rust-syntax regex and `--case-sensitive` when case matters. Without `--regex`, `|`, `\(`, and `.*` match those characters literally. Matching is per line. `--sort path` gives a stable order instead of relevance.
+- **refs**: exact, case-sensitive name. `--kind call|type|import|implementation`. Every language records `call` references. `type` references exist only for Dart, Go, and TypeScript/TSX; `import` references only for Dart and JavaScript/TypeScript/TSX; `implementation` references for Dart, Java, JavaScript/TypeScript/TSX, PHP, and Rust. In other languages, find type uses and imports with `lantern code`. `enclosing` names the definition that contains the reference.
+- **graph**: `--direction callers|callees|both`. It follows calls only; use `refs` for type uses, imports, and `extends`/`implements` where the language records them (see **refs**). A node with kind `file` stands for calls outside any definition. Names in `unresolved` have no definition in the index (often library calls). Code outside tests never resolves to a definition in a test file.
+- **outline**: accepts a path relative to the current directory or an absolute path. For a path that is not in the index, the error lists indexed files with the same file name.
+
+## Know the limits
+
+- **Name resolution, not types.** `refs` and `graph` link by name (`"resolution": "name"`). Two unrelated functions with the same name share references and edges. Check the node paths before you trust an edge; narrow with `--path` or `--kind`.
+- **Generated files** (lockfiles, files marked `linguist-generated` or `linguist-vendored` in `.gitattributes`) are left out of `symbols`, `refs`, and `graph`, and ranked last in `code`. Add `--include-generated` to include them.
+- **What is indexed.** In a Git repository: tracked files plus untracked files that Git does not ignore. Outside Git: all files except `.gitignore` matches and the defaults (dot-files, `node_modules/`, `dist/`, `build/`, `coverage/`, `target/`, `vendor/`). `.lanternignore` (gitignore syntax) excludes more in both. Files over 1 MiB (`--max-file-size`) and binary files are not searchable as text.
+- **Nested repositories** (submodules that are checked out) are indexed with the repository that contains them; their paths carry the submodule prefix.
+- **Windows: files open for writing.** In a Git repository on Windows, Lantern takes file metadata from directory listings, as Git does with `core.fscache`. It does not see an edit to a file that another process still holds open for writing until that process closes the file. It also does not see an edit made through another name of a hard-linked file until that name is opened. Editor saves close the file, so they are not affected.
+
+## Handle errors
+
+Errors go to stderr as `lantern: <message>` (with `--json`: `{"error":{"code":"...","message":"..."}}`). Act on the exit code:
+
+| Exit | Code | What to do |
+|---|---|---|
+| 1 | `failure` | Read the message. "not indexed" with `--stale-ok`: drop `--stale-ok` or run `lantern index`. |
+| 2 | `usage` | Fix the arguments (bad flag, limit, glob, cursor from another query, `--max-bytes` too small). |
+| 3 | `root_moved` | A folder that was indexed alone is now inside a Git repository. Run from the intended root. |
+| 4 | `stale_cursor` | The index changed between pages. Run the query again without `--cursor`. |
+| 75 | `temporary` | Another refresh holds the lock, files kept changing, or (`index` only) a reader blocked cleanup. Retry after a short wait. |
+
+## Speed
+
+- Use `--stale-ok` when you run many queries in a row and the files have not changed (see **Several queries in a row**). It skips the refresh and labels results `stale`.
+- In a very large repository the first query can take minutes. Run `lantern index` once up front if you can.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.