@nexapp/code-map 0.1.0

package/bin.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const ext = process.platform === 'win32' ? '.exe' : '';
+const binaryName = `code-map${ext}`;
+
+// 1. Co-located binary — present when installed via `npm install -g /local/path`
+const localBin = path.join(__dirname, 'bin', binaryName);
+if (fs.existsSync(localBin)) {
+  try {
+    execFileSync(localBin, process.argv.slice(2), { stdio: 'inherit' });
+  } catch (err) {
+    process.exit(err.status ?? 1);
+  }
+  process.exit(0);
+}
+
+// 2. Platform package — present when installed from the npm registry
+const PLATFORMS = {
+  'darwin-arm64': '@nexapp/code-map-darwin-arm64',
+  'darwin-x64':   '@nexapp/code-map-darwin-x64',
+  'linux-arm64':  '@nexapp/code-map-linux-arm64',
+  'linux-x64':    '@nexapp/code-map-linux-x64',
+  'win32-x64':    '@nexapp/code-map-win32-x64',
+};
+
+const key = `${process.platform}-${process.arch}`;
+const pkg = PLATFORMS[key];
+
+if (!pkg) {
+  console.error(`code-map: unsupported platform ${key}`);
+  process.exit(1);
+}
+
+let binPath;
+try {
+  binPath = require.resolve(`${pkg}/bin/${binaryName}`);
+} catch {
+  console.error(
+    `code-map: could not find binary for ${key}.\n` +
+    `Try reinstalling: npm install ${pkg}`
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nexapp/code-map",
+  "version": "0.1.0",
+  "description": "TypeScript dependency analyzer and visualizer — analyze imports, find unused exports, and explore project graphs.",
+  "keywords": [
+    "typescript",
+    "dependencies",
+    "imports",
+    "visualization",
+    "analysis"
+  ],
+  "homepage": "https://git.nexapptech.com/internal/code-map",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@git.nexapptech.com/internal/code-map.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "code-map": "./bin.js"
+  },
+  "files": [
+    "bin.js",
+    "bin/",
+    "plugin/"
+  ],
+  "optionalDependencies": {
+    "@nexapp/code-map-darwin-arm64": "0.1.0",
+    "@nexapp/code-map-darwin-x64": "0.1.0",
+    "@nexapp/code-map-linux-x64": "0.1.0",
+    "@nexapp/code-map-linux-arm64": "0.1.0",
+    "@nexapp/code-map-win32-x64": "0.1.0"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "code-map",
+  "description": "TypeScript dependency analysis. Answers questions about file dependencies, unused exports, and project-wide import cycles using the code-map tool.",
+  "version": "1.0.0",
+  "author": {
+    "name": "spaceparanoids"
+  },
+  "skills": [
+    "skills/analyze-file",
+    "skills/find-unused-exports",
+    "skills/project-overview"
+  ]
+}

package/plugin/skills/analyze-file/SKILL.md

@@ -0,0 +1,39 @@
+---
+
+name: analyze-file
+description: Show what a specific TypeScript file imports and what imports it. Use when asked about a file's dependencies, dependents, or role in the project.
+
+---
+
+Analyze a single file's dependencies from a code-map snapshot.
+
+## Step 1: Locate the snapshot
+
+Look for `code-map.json` in the project root. If it does not exist, tell the user:
+
+> No code-map snapshot found. Run:
+> `npx code-map index .`
+> Then run this skill again.
+
+If it is more than a day old (check `meta.indexed_at`), suggest re-indexing before continuing.
+
+## Step 2: Identify the file
+
+Ask the user which file to analyze if not already specified. Match against `files[].id` in the snapshot.
+
+## Step 3: Find dependencies
+
+From `dependencies[]`:
+
+- **Outgoing** (`from` starts with the file path): what this file imports
+- **Incoming** (`to` starts with the file path): what imports this file
+- **Cycles**: any entry in `cycles[]` that involves this file
+
+Decode the entity ref format:
+- `path/to/file.ts[file]` — file-level import
+- `path/to/file.ts:Name[class|function|interface|enum|type]` — named entity
+- `lib:react` — external library
+
+## Step 4: Report
+
+List outgoing imports grouped by target file, incoming imports grouped by source file, and any cycles. Keep it factual.

package/plugin/skills/find-unused-exports/SKILL.md

@@ -0,0 +1,56 @@
+---
+
+name: find-unused-exports
+description: Find exported symbols in the TypeScript project that nothing imports. Use when asked about dead code, unused exports, or cleanup opportunities.
+
+---
+
+Find unused exports from a code-map snapshot.
+
+## Step 1: Locate the snapshot
+
+Look for `code-map.json` in the project root. If it does not exist, tell the user:
+
+> No code-map snapshot found. Run:
+> `npx code-map index .`
+> Then run this skill again.
+
+If `meta.schema_version` is less than 2, the snapshot was built with an older
+version of code-map that did not record exports. Tell the user:
+
+> This snapshot was built with an older version of code-map and does not contain
+> export data. Re-index the project to enable unused-export analysis:
+> `npx code-map index .`
+
+## Step 2: Build the used-symbol set
+
+Collect every `to` value from the `dependencies` array that is not a `lib:` entry
+and does not end with `:*` (namespace imports). These are all symbols that are
+explicitly imported somewhere in the project.
+
+Also collect the set of files that are namespace-imported (files whose path
+appears in a `to` ending with `:*`). Exports from these files cannot be reliably
+checked — they will be skipped.
+
+## Step 3: Find unused exports
+
+For each entry in `files[].exports`:
+
+- Skip the file entirely if it is in the namespace-imported set.
+- An export `{ name, kind }` from file `F` is **used** if any entry in the
+  used-symbol set starts with `F:name[`.
+- Otherwise it is **unused**.
+
+## Step 4: Report
+
+1. **Summary**: "X unused exports found across Y files (Z files skipped due to
+   namespace imports)."
+2. **Grouped by file**: for each file with unused exports, list the symbol name
+   and kind.
+3. **Skipped files**: if any files were skipped due to namespace imports, list
+   them and explain why (a `import * as X` elsewhere means all exports of that
+   file are potentially reachable).
+4. Remind the user to verify before deleting — the analysis is static and cannot
+   detect dynamic access patterns or consumers outside the indexed project root.
+
+If there are zero unused exports, say so and stop.

package/plugin/skills/project-overview/SKILL.md

@@ -0,0 +1,49 @@
+---
+
+name: project-overview
+description: Get a high-level view of the TypeScript project's import graph — file count, dependency edges, entry points, and import cycles. Use when asked about project structure, architecture, or circular dependencies.
+
+---
+
+Generate a project-wide dependency overview from a code-map snapshot.
+
+## Step 1: Locate the snapshot
+
+Look for `code-map.json` in the project root. If it does not exist, tell the user:
+
+> No code-map snapshot found. Run:
+> `npx code-map index .`
+> Then run this skill again.
+
+If it is more than a day old (check `meta.indexed_at`), suggest re-indexing before continuing.
+
+## Step 2: Derive the graph
+
+From `code-map.json`:
+
+- **Files**: the `files` array (`id` field is the path)
+- **Edges**: strip entity detail from `from`/`to` in `dependencies` — take the part before the first `:` or `[`, skip `lib:` entries, deduplicate
+- **Cycles**: the `cycles` array
+- **Entry points**: files whose `id` does not appear in any stripped `to` value
+
+## Step 3: Report
+
+**Stats**: total files, total file-level dependency edges, number of cycles.
+
+**Entry points**: files that nothing else imports — the roots of the dependency tree. List up to 10; if more, state the count.
+
+**Cycles**: if any, this is the most important finding. List every pair:
+
+```
+CYCLE: src/a.ts <-> src/b.ts
+```
+
+Note that circular imports can cause initialization-order bugs at runtime.
+
+**Snapshot age**: read `meta.indexed_at` and report how old the snapshot is. If more than a day old, recommend re-indexing:
+
+```bash
+npx code-map index .
+```
+
+Keep the report factual. Do not speculate about architecture beyond what the data shows.