Egonex-AI/Understand-Anything / understand-anything-plugin/skills/understand
understand
VerifiedAnalyze a codebase to produce an interactive knowledge graph for understanding architecture, components, and relationships
extract-structure.mjs
View on GitHub#!/usr/bin/env node
/**
* extract-structure.mjs
*
* Deterministic structural extraction script for the file-analyzer agent.
* Uses PluginRegistry (TreeSitterPlugin + non-code parsers) from @understand-anything/core
* to replace the LLM-generated throwaway regex scripts in Phase 1.
*
* Usage:
* node extract-structure.mjs <input.json> <output.json>
*
* Input JSON:
* { projectRoot, batchFiles: [{path, language, sizeLines, fileCategory}], batchImportData }
*
* Output JSON:
* { scriptCompleted, filesAnalyzed, filesSkipped, filesUnreadable, results: [...] }
*
* `filesSkipped` lists every batch file that produced no result, and
* `filesUnreadable` is the subset of those that could not be read at all
* (ENOENT / EACCES / ...). Only the latter points at a broken `projectRoot`;
* a file skipped for having no registered parser is expected and benign.
*/
import { createRequire } from 'node:module';
import { dirname, resolve, join } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
import {
analyzeFileWithOutcomes,
buildResult as buildExtractResult,
} from './extract-structure-result.mjs';
export {
analyzeFileWithOutcomes,
buildResult,
} from './extract-structure-result.mjs';
const __dirname = dirname(fileURLToPath(import.meta.url));
// skills/understand/ -> plugin root is two dirs up
const pluginRoot = resolve(__dirname, '../..');
const require = createRequire(resolve(pluginRoot, 'package.json'));
// ---------------------------------------------------------------------------
// Resolve @understand-anything/core
//
// Node ESM dynamic import() requires a file:// URL on Windows; passing a raw
// absolute path like "C:\..." throws ERR_UNSUPPORTED_ESM_URL_SCHEME because the
// loader parses "C:" as a URL scheme. Wrap both resolutions in pathToFileURL().
// ---------------------------------------------------------------------------
let core;
try {
core = await import(pathToFileURL(require.resolve('@understand-anything/core')).href);
} catch {
// Fallback: direct path for installed plugin cache layouts
core = await import(pathToFileURL(resolve(pluginRoot, 'packages/core/dist/index.js')).href);
}
const { TreeSitterPlugin, PluginRegistry, builtinLanguageConfigs, registerAllParsers } = core;
// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------
async function main() {
const [,, inputPath, outputPath] = process.argv;
if (!inputPath || !outputPath) {
process.stderr.write('Usage: node extract-structure.mjs <input.json> <output.json>\n');
process.exit(1);
}
// Read input
const inputRaw = readFileSync(inputPath, 'utf-8');
const input = JSON.parse(inputRaw);
const { projectRoot, batchFiles, batchImportData } = input;
if (!projectRoot || !Array.isArray(batchFiles)) {
throw new Error('Invalid input: must contain projectRoot and batchFiles array');
}
// Create tree-sitter plugin with all configs that have WASM grammars
const tsConfigs = builtinLanguageConfigs.filter(c => c.treeSitter);
const tsPlugin = new TreeSitterPlugin(tsConfigs);
await tsPlugin.init();
// Create registry and register tree-sitter + all non-code parsers
const registry = new PluginRegistry();
registry.register(tsPlugin);
registerAllParsers(registry);
const results = [];
const filesSkipped = [];
const filesUnreadable = [];
const analysisOutcomes = {
structure: { succeeded: 0, failed: 0 },
callGraph: { succeeded: 0, failed: 0, skipped: 0 },
};
for (const file of batchFiles) {
const absolutePath = join(projectRoot, file.path);
// Read file content
let content;
try {
content = readFileSync(absolutePath, 'utf-8');
} catch (err) {
// Keep the path in filesSkipped so "every batch file is accounted for"
// still holds for callers that only read that field, but also record it
// in filesUnreadable so a wrong projectRoot stays distinguishable from a
// file that merely has no parser.
filesSkipped.push(file.path);
filesUnreadable.push({
path: file.path,
code: typeof err?.code === 'string' ? err.code : null,
});
continue;
}
// Line counts. POSIX text files end in a trailing newline, which makes
// `split('\n')` produce one extra empty element. Match `wc -l` semantics
// (used by the project scanner for `sizeLines`) so the two counts agree.
const lines = content.split('\n');
const totalLines = content.endsWith('\n') ? Math.max(0, lines.length - 1) : lines.length;
const nonEmptyLines = lines.filter(l => l.trim().length > 0).length;
const { analysis, callGraph, structureOutcome, callGraphOutcome } =
analyzeFileWithOutcomes(registry, file, content);
if (structureOutcome === 'skipped') {
filesSkipped.push(file.path);
continue;
}
analysisOutcomes.structure[structureOutcome] += 1;
analysisOutcomes.callGraph[callGraphOutcome] += 1;
// Build result object
const result = buildExtractResult(file, totalLines, nonEmptyLines, analysis, callGraph, batchImportData);
results.push(result);
}
// Write output
const output = {
scriptCompleted: true,
filesAnalyzed: results.length,
filesSkipped,
filesUnreadable,
analysisOutcomes,
results,
};
writeFileSync(outputPath, JSON.stringify(output, null, 2), 'utf-8');
if (!existsSync(outputPath)) {
throw new Error(`output file missing after write: ${outputPath}`);
}
if (filesUnreadable.length > 0) {
process.stderr.write(
`extract-structure.mjs: ${filesUnreadable.length}/${batchFiles.length} batch file(s) could not be read ` +
`(e.g. ${filesUnreadable[0].path} [${filesUnreadable[0].code ?? 'unknown error'}]); ` +
`verify that projectRoot resolves: ${projectRoot}\n`,
);
}
// A batch where nothing at all could be read is always a configuration
// error (wrong projectRoot, mismatched mount, ...), never a property of the
// analyzed code. Report it as a failure instead of a clean run so callers
// cannot mistake it for "every file simply lacks a parser".
if (batchFiles.length > 0 && filesUnreadable.length === batchFiles.length) {
throw new Error(
`no file in the batch could be read (${filesUnreadable.length}/${batchFiles.length}); ` +
`projectRoot is likely wrong: ${projectRoot}`,
);
}
}
// ---------------------------------------------------------------------------
// Run only when executed directly as a CLI; importing the module (e.g. from
// tests) must not trigger main().
//
// Canonicalize both sides through realpathSync. Node ESM resolves
// import.meta.url through symlinks but pathToFileURL(process.argv[1]) preserves
// them, so a raw equality check silently no-ops when the script is invoked via
// a symlinked plugin install path (the default in Claude Code / Copilot CLI
// caches). See GitHub issue #162.
// ---------------------------------------------------------------------------
function isCliEntry() {
if (!process.argv[1]) return false;
try {
const modulePath = realpathSync(fileURLToPath(import.meta.url));
const argvPath = realpathSync(process.argv[1]);
return modulePath === argvPath;
} catch {
return false;
}
}
if (isCliEntry()) {
try {
await main();
} catch (err) {
process.stderr.write(`extract-structure.mjs failed: ${err.message}\n${err.stack}\n`);
process.exit(1);
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |