Spectrum Diff Core

Shared core library for Spectrum diff generation tools (tokens, component schemas, etc.).

Overview

This package provides the foundational components for creating consistent diff tools across the Spectrum ecosystem. It includes:

- Core utilities: File import/export, diff operations, type checking
- CLI framework: Base CLI structure with consistent option handling
- Template system: Handlebars-based formatting with shared helpers
- Output handling: File output and console formatting

Installation

``bash
pnpm add @adobe/spectrum-diff-core
`

Usage

$3

`javascript
import { BaseCLI, FileLoader, detailedDiff } from "@adobe/spectrum-diff-core";

class MyDiffTool extends BaseCLI {
constructor() {
super({
toolName: "mydiff",
dataType: "mydata",
packagePath: "packages/mydata/src",
manifestFile: "manifest.json",
});
}

async generateDiff(original, updated) {
const changes = detailedDiff(original, updated);
// Add your specific change detection logic here
return this.processChanges(changes);
}
}
`

$3

`javascript
import { FileLoader } from "@adobe/spectrum-diff-core";

const loader = new FileLoader();

// Load from remote repository
const remoteData = await loader.loadRemoteFiles(
["file1.json", "file2.json"],
"v1.0.0",
null,
"owner/repo",
"api-key",
"packages/data/src",
);

// Load from local filesystem
const localData = await loader.loadLocalFiles("packages/data/src", [
"file1.json",
"file2.json",
]);
`

$3

`javascript
import { HandlebarsFormatter } from "@adobe/spectrum-diff-core";

const formatter = new HandlebarsFormatter({
template: "cli",
dataType: "tokens",
});

const output = await formatter.format(diffResult, options);
`

CLI Framework

The BaseCLI class provides a consistent CLI structure:

`bash
mydiff report --old-version v1.0.0 --new-version v1.1.0 --format markdown --output report.md
`

Common CLI Options:

- --old-[type]-version / --new-[type]-version (version comparison)
- --old-[type]-branch / --new-[type]-branch (branch comparison)
- --local (local file comparison)
- --format (cli, markdown, handlebars)
- --template (built-in template names)
- --output (file output)
- --debug (debug output)

Template System

Templates are organized by data type:

`
templates/
├── base/ # Shared templates
│ ├── cli.hbs
│ ├── markdown.hbs
│ └── json.hbs
├── tokens/ # Token-specific templates
└── schemas/ # Schema-specific templates
`

$3

- {{hasKeys obj}} - Check if object has properties
- {{totalItems result}} - Calculate total number of changes
- {{capitalize str}} - Capitalize string
- {{cleanPath path}} - Clean up property paths
- {{formatDate date}} - Format timestamps
- {{hilite}}, {{error}}, {{passing}} - Terminal colors
- {{bold}}, {{dim}}, {{emphasis}} - Text formatting

API Reference

$3

- detailedDiff(original, updated) - Generate detailed diff
- isObject(obj), isString(str), etc. - Type checking utilities
- deepClone(obj) - Deep clone objects
- getNestedProperty(obj, path) - Safe property access

$3

- FileLoader - Main file loading orchestrator
- RemoteFileFetcher - Handle remote repository fetching
- LocalFileSystem - Handle local file operations

$3

- BaseCLI - Base class for creating CLI tools
- normalizeOptions(options) - Normalize CLI options
- determineStrategy(options) - Determine loading strategy

$3

- HandlebarsFormatter - Template-based formatting
- storeOutput(content, path) - File output utility

Development

`bash


Install dependencies

pnpm install

Run tests

pnpm test

Lint code

pnpm lint

Fix linting issues

pnpm lint:fix
``

License

Apache-2.0