skott

If you want to see links between high-level architectural components rather than individual files, use the groupBy option in SkottConfig.

When groupBy is provided, getStructure() returns a groupedGraph. This graph contains nodes representing the groups, where each node's body includes:

• size: The aggregate size of all files in the group.
• files: An array of file paths belonging to that group.
• thirdPartyDependencies: The combined set of third-party dependencies for the group.
• builtinDependencies: The combined set of built-in dependencies for the group.

Example usage:

const instance = await skott({
  groupBy: (path) => {
    if (path.includes("core")) return "core";
    if (path.includes("feature-a")) return "feature-a";
    return undefined;
  }
}).initialize();

const { groupedGraph } = instance.getStructure();
// Access a specific group
const coreGroup = groupedGraph["core"];

const instance = await skott({
  groupBy: (path) => {
    if (path.includes("core")) return "core";
    if (path.includes("feature-a")) return "feature-a";
    return undefined;
  }
}).initialize();

const { groupedGraph } = instance.getStructure();

// groupedGraph["core"] contains aggregated data for all 'core' files

When using the API, you can pass a configuration object to skott() to control the scope and depth of the analysis.

Configuration Keys

• cwd: (string) The current working directory to start the analysis from.
• entrypoint: (string) A specific file path to start traversal from. This will discard all files not part of the graph reachable from this entrypoint.
• ignorePatterns: (string[]) An array of glob patterns to exclude from the analysis.
• dependencyTracking: (object) Controls which types of dependencies are collected.
  • builtin: (boolean) Whether to track built-in Node.js modules.
  • thirdParty: (boolean) Whether to track third-party npm dependencies.
  • typeOnly: (boolean) Whether to track TypeScript type-only imports.

// Example configuration
await skott({
    cwd: "packages/skott",
    entrypoint: "packages/skott/index.ts",
    ignorePatterns: ["**/node_modules/**"],
    dependencyTracking: {
        builtin: true,
        thirdParty: true,
        typeOnly: true
    }
});

Skott uses an incremental caching system to speed up analysis by storing previously computed node data and configuration hashes.

How it works:

1. Configuration Hashing: On initialization, Skott hashes the current SkottConfig. If the configuration has changed since the last run, the existing cache is invalidated and a new one is created.
2. File Hashing: Each source file is hashed based on its content. This allows Skott to determine if a file's dependencies or structure need re-computation.
3. Cache Storage: The cache is stored in a file named .skott/cache.json in the current working directory.
4. Incremental Mode: Caching is only active if incremental: true is set in your SkottConfig. If disabled, the cache is ignored.

Cache Invalidation:

• If the SkottConfig changes, the entire cache is wiped.
• If a file's content changes, its hash will no longer match the cached version, triggering a re-analysis of that node.

The skott CLI starts a dependency analysis to build a graph of your project. You can specify an optional [entrypoint] file and use various flags to control how the graph is built, what is tracked, and how the results are displayed.

Common Usage Examples

# Analyze a specific entrypoint and display as a file tree
./node_modules/.bin/skott src/index.js --displayMode=file-tree --no-trackTypeOnlyDependencies

# Specify file extensions and a custom tsconfig
./node_modules/.bin/skott --fileExtensions=.ts,.tsx --tsconfig=tsconfig.base.json

# Show circular dependencies in raw mode with watch mode enabled
./node_modules/.bin/skott --showCircularDependencies --displayMode=raw --watch

#!/usr/bin/env node
# Example usage commands:
./node_modules/.bin/skott src/index.js --displayMode=file-tree --no-trackTypeOnlyDependencies
./node_modules/.bin/skott --fileExtensions=.ts,.tsx --tsconfig=tsconfig.base.json
./node_modules/.bin/skott --showCircularDependencies --displayMode=raw --watch