Skip to content

Egonex-AI/Understand-Anything / understand-anything-plugin/skills/understand

understand

Verified

Analyze a codebase to produce an interactive knowledge graph for understanding architecture, components, and relationships

FileKindSize
SKILL.mdskill md67.9 KB
build-fingerprints.mjsscript3.7 KB
compute-batches.mjsscript26.4 KB
extract-import-map.mjsscript81.6 KB
extract-structure-result.mjsscript9.8 KB
extract-structure.mjsscript7.4 KB
finalize-incremental.mjsscript19.7 KB
frameworks/django.mdmarkdown4.7 KB
frameworks/express.mdmarkdown4.3 KB
frameworks/fastapi.mdmarkdown4.3 KB
frameworks/flask.mdmarkdown3.4 KB
frameworks/gin.mdmarkdown4.5 KB
frameworks/nextjs.mdmarkdown4.3 KB
frameworks/rails.mdmarkdown5.3 KB
frameworks/react.mdmarkdown3.7 KB
frameworks/spring.mdmarkdown4.9 KB
frameworks/vue.mdmarkdown4.4 KB
generate-ignore.mjsscript2.5 KB
languages/cpp.mdmarkdown2.5 KB
languages/csharp.mdmarkdown2.6 KB
languages/css.mdmarkdown2.0 KB
languages/dockerfile.mdmarkdown1.9 KB
languages/go.mdmarkdown2.4 KB
languages/graphql.mdmarkdown1.9 KB
languages/html.mdmarkdown1.9 KB
languages/java.mdmarkdown2.4 KB
languages/javascript.mdmarkdown2.3 KB
languages/json.mdmarkdown1.7 KB
languages/kotlin.mdmarkdown2.5 KB
languages/markdown.mdmarkdown1.9 KB
languages/php.mdmarkdown2.5 KB
languages/protobuf.mdmarkdown1.8 KB
languages/python.mdmarkdown2.6 KB
languages/ruby.mdmarkdown2.4 KB
languages/rust.mdmarkdown2.4 KB
languages/scala.mdmarkdown3.2 KB
languages/shell.mdmarkdown1.8 KB
languages/sql.mdmarkdown2.0 KB
languages/swift.mdmarkdown2.5 KB
languages/terraform.mdmarkdown2.1 KB
languages/typescript.mdmarkdown2.5 KB
languages/yaml.mdmarkdown1.9 KB
locales/en.mdmarkdown1.5 KB
locales/ja.mdmarkdown2.1 KB
locales/ko.mdmarkdown1.9 KB
locales/ru.mdmarkdown3.1 KB
locales/vi.mdmarkdown2.1 KB
locales/zh-TW.mdmarkdown1.7 KB
locales/zh.mdmarkdown1.7 KB
merge-batch-graphs.pyscript57.6 KB
merge-subdomain-graphs.pyscript16.1 KB
normalize-tour.mjsscript3.4 KB
prepare-incremental.mjsscript25.4 KB
prepare-symbol-retry.mjsscript7.4 KB
prune-code-lessons.mjsscript4.2 KB
scan-project.mjsscript31.5 KB
validate-incremental-symbols.mjsscript25.8 KB

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);
  }
}
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall