### Install Repolinter with npm Source: https://todogroup.github.io/repolinter Install Repolinter globally using npm. Requires Node.js >= v10. ```bash npm install -g repolinter ``` -------------------------------- ### defaultFormatter output example Source: https://todogroup.github.io/repolinter Example output from the defaultFormatter, showing the CLI-style LintResult with checkmarks and status messages for each rule. ```text ✔ license-file-exists: found (LICENSE) ✔ readme-file-exists: found (README.md) ✔ contributing-file-exists: found (CONTRIBUTING) ✔ code-of-conduct-file-exists: found (CODE-OF-CONDUCT) ✔ changelog-file-exists: found (CHANGELOG) ✔ readme-references-license: File README.md contains license ✔ license-detectable-by-licensee: Licensee identified the license for project: Apache License 2.0 ✔ test-directory-exists: found (tests) ✔ integrates-with-ci: found (.travis.yml) ✔ source-license-headers-exist: The first 5 lines of 'index.js' contain all of the requested patterns. ... ✔ github-issue-template-exists: found (ISSUE_TEMPLATE) ✔ github-pull-request-template-exists: found (PULL_REQUEST_TEMPLATE) ✔ package-metadata-exists: found (Gemfile) ✔ package-metadata-exists: found (package.json) ``` -------------------------------- ### Example Output of repolinter lint Source: https://todogroup.github.io/repolinter Example output from running repolinter lint on a directory, showing successful checks and exit code 0. ```bash repolinter % repolinter lint . Target directory: Lint: ✔ license-file-exists: Found file (LICENSE) ✔ readme-file-exists: Found file (README.md) ✔ contributing-file-exists: Found file (CONTRIBUTING) ✔ code-of-conduct-file-exists: Found file (CODE-OF-CONDUCT) ✔ changelog-file-exists: Found file (CHANGELOG) ... repolinter % echo $? 0 ``` -------------------------------- ### Numerical axiom comparisons (contributor-count) Source: https://todogroup.github.io/repolinter Example using a numerical axiom (`contributor-count`) with numerical comparisons in the `where` conditional. Note that numerical comparisons on non-numerical axioms always fail. ```json { "axioms": { "contributor-count": "contributors" }, "rules": { "my-rule": { "where": ["contributors>6", "contributors<200"], // ... } } } ``` ```yaml axioms: contributor-count: contributors rules: my-rule: where: - contributors>6 - contributors<200 rule: ... ``` -------------------------------- ### markdownFormatter output example Source: https://todogroup.github.io/repolinter Example output from the markdownFormatter, showing a markdown document with a summary table of lint results. ```markdown # Repolinter Report This Repolinter run generated the following results: | ❗ Error | ❌ Fail | ⚠️ Warn | ✅ Pass | Ignored | Total | |---|---|---|---|---|---| | 0 | 0 | 0 | 15 | 10 | 25 | ... ``` -------------------------------- ### Configure licensee axiom Source: https://todogroup.github.io/repolinter Configure the licensee axiom to detect the repository license and use a license identifier in a rule's where clause. Requires licensee installed in PATH or Repolinter's directory. ```json { "axioms": { "licensee": "license" }, "rules": { "my-rule": { "where": ["license=Apache-2.0"], // ... } } } ``` -------------------------------- ### Axiom usage in ruleset (packagers) Source: https://todogroup.github.io/repolinter Example ruleset configuration using an axiom to detect the packaging system. The `where` conditional uses the axiom target `package-type` with a string comparison. ```json { "$schema": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/schema.json", "version": 2, "axioms": { "packagers": "package-type" }, "rules": { "this-only-runs-if-npm": { "level": "error", "where": ["package-type=npm"], "rule": { /* ... */ } } } } ``` ```yaml version: 2 axioms: packagers: package-type rules: this-only-runs-if-npm: level: error where: [package-type=npm] rule: ... ``` -------------------------------- ### Format output as JSON with --format json Source: https://todogroup.github.io/repolinter Use the --format flag with 'json' to output results in JSON format. The example shows the command and a truncated JSON response. ```bash repolinter % repolinter lint --format json . {"params":{"targetDir":"/Users/nkoontz/Documents/code/repolinter","filterPaths":[],... ``` -------------------------------- ### Format output as Markdown with --format markdown Source: https://todogroup.github.io/repolinter Use the --format flag with 'markdown' to output results in Markdown format. The example shows the command and a truncated Markdown report. ```bash repolinter % repolinter lint --format markdown . # Repolinter Report This Repolinter run generated the following results: | ❗ Error | ❌ Fail | ⚠️ Warn | ✅ Pass | Ignored | Total | |---|---|---|---|---|---| | 0 | 0 | 0 | 15 | 10 | 25 | ... ``` -------------------------------- ### Configure linguist axiom Source: https://todogroup.github.io/repolinter Configure the linguist axiom to detect programming languages and use a language value in a rule's where clause. Requires linguist installed in PATH or Repolinter's directory. ```json { "axioms": { "linguist":" language" }, "rules": { "my-rule": { "where": ["language=javascript"], // ... } } } ``` -------------------------------- ### Fix Configuration JSON Schema Template Source: https://todogroup.github.io/repolinter Template for a fix configuration JSON schema. Use this as a starting point when creating a new fix. The $id should be updated to point to the actual fix configuration file. ```json { "$schema": "http://json-schema.org/draft-07/schema", "$id": "https://raw.githubusercontent.com/todogroup/repolinter/master/fixes/-config.json", "type": "object", "properties": {} } ``` -------------------------------- ### FileSystem Class Source: https://todogroup.github.io/repolinter Documentation for the FileSystem class and its methods, including constructor, static and instance methods for file operations. ```APIDOC ## new FileSystem(targetDir, filterPaths) ### Description Utility filesystem class that scopes operations to a given set of directories and a CWD. ### Constructor `new FileSystem(targetDir: any, filterPaths: any)` ### Parameters - **targetDir** (any) - Default `'.'` - The target directory. - **filterPaths** (any) - Default `[]` - Paths to filter. ``` ```APIDOC ## FileSystem.fileExists(file) ### Description Asynchronously checks if a file exists using fs.access. ### Method `fileExists(file: string): Promise` ### Parameters - **file** (string) - An absolute path to verify the existence of. ### Returns `Promise` - Whether or not the path exists. ``` ```APIDOC ## FileSystem.relativeFileExists(file) ### Description Asynchronously checks if a file exists using fs.access. ### Method `relativeFileExists(file: string): Promise` ### Parameters - **file** (string) - A path relative to targetDir to check the existence of. ### Returns `Promise` - Whether or not the path exists. ``` ```APIDOC ## FileSystem.findFirst(globs, nocase) ### Description Find the first file or directory matching a list of globs. Globs are searched from first to last. Returns the relative path of that file or directory, or undefined if none was found. ### Method `findFirst(globs: (string | Array), nocase: boolean): Promise<(undefined | string)>` ### Parameters - **globs** ((string | Array)) - The globs to search with. - **nocase** (boolean) - Whether or not to ignore case-sensitivity. ### Returns `Promise<(undefined | string)>` - A path relative to this.targetDir, or undefined if no items were found. ``` ```APIDOC ## FileSystem.findFirstFile(globs, nocase) ### Description Find the first file matching a list of globs. Globs are searched from first to last. Returns the relative path of that file, or undefined if none was found. ### Method `findFirstFile(globs: (string | Array), nocase: boolean): Promise<(undefined | string)>` ### Parameters - **globs** ((string | Array)) - The globs to search with. - **nocase** (boolean) - Whether or not to ignore case-sensitivity. ### Returns `Promise<(undefined | string)>` - A path relative to this.targetDir, or undefined if no items were found. ``` ```APIDOC ## FileSystem.findAllFiles(globs, nocase) ### Description Find all files matching a list of globs. Globs are searched from first to last. Returns the relative path of all files, or undefined if none was found. Automatically removes symlinks from results. ### Method `findAllFiles(globs: (string | Array), nocase: boolean): Promise>` ### Parameters - **globs** ((string | Array)) - The globs to search with. - **nocase** (boolean) - Whether or not to ignore case-sensitivity. ### Returns `Promise>` - A list of paths relative to this.targetDir. ``` ```APIDOC ## FileSystem.findAll(globs, nocase = false) ### Description Find all files or directories matching a list of globs. Globs are searched from first to last. Returns the relative path of all items, or undefined if none was found. Automatically removes symlinks from results. ### Method `findAll(globs: (string | Array), nocase: boolean?): Promise>` ### Parameters - **globs** ((string | Array)) - The globs to search with. - **nocase** (boolean?) - Default `false` - Whether or not to ignore case-sensitivity. ### Returns `Promise>` - A list of paths relative to this.targetDir. ``` ```APIDOC ## FileSystem.getFileContents(relativeFile) ### Description Get the contents of a file in utf8 given a relative path. ### Method `getFileContents(relativeFile: string): Promise<(string | undefined)>` ### Parameters - **relativeFile** (string) - A path relative to this.targetDir. ### Returns `Promise<(string | undefined)>` - A string with the file contents, or undefined if the file is not found. ``` ```APIDOC ## FileSystem.setFileContents(relativeFile, contents) ### Description Set the contents of a file in utf8 given a relative path and contents. ### Method `setFileContents(relativeFile: string, contents: string): Promise` ### Parameters - **relativeFile** (string) - A path relative to this.targetDir. - **contents** (string) - A string with the file contents. ### Returns `Promise` ``` ```APIDOC ## FileSystem.removeFile(relativeFile) ### Description Remove the file at the specified path. ### Method `removeFile(relativeFile: string): Promise` ### Parameters - **relativeFile** (string) - A path relative to this.targetDir. ### Returns `Promise` ``` -------------------------------- ### apache-notice rule equivalent configuration Source: https://todogroup.github.io/repolinter Equivalent configuration for the apache-notice rule, which checks for a NOTICE file in the repository root. ```json { "type": "file-existence", "options": {"globsAny": ["NOTICE*"]} } ``` -------------------------------- ### Configure contributor-count axiom Source: https://todogroup.github.io/repolinter Configure the contributor-count axiom to count contributors via gitlog and use numerical comparisons in a rule's where clause. ```json { "axioms": { "contributor-count": "contributors" }, "rules": { "my-rule": { "where": ["contributors>6", "contributors<200"], // ... } } } ``` -------------------------------- ### lint(targetDir, filterPaths, ruleset, dryRun) Source: https://todogroup.github.io/repolinter Runs the repolinter engine on a specified directory, with optional filter paths, custom ruleset, and dry-run mode. ```APIDOC ## lint(targetDir, filterPaths, ruleset, dryRun) ### Description An exposed function for the repolinter engine. Use this function to run repolinter on a specified directory targetDir. You can also optionally specify which paths to allowlist (filterPaths), whether or not to actually commit modifications (fixes), and a custom ruleset object to use. This function will not throw an error on failure, instead indicating that an error has occurred in returned value. ### Method lint ### Parameters - **targetDir** (string) - Required - The directory of the repository to lint. - **filterPaths** (Array?) - Optional - A list of directories to allow linting of, or [] for all. Default: `[]`. - **ruleset** ((Object | string | null)?) - Optional - A custom ruleset object with the same structure as the JSON ruleset configs, or a string path to a JSON config. Set to null for repolinter to automatically find it in the repository. Default: `null`. - **dryRun** (boolean?) - Optional - If true, repolinter will report suggested fixes, but will make no disk modifications. Default: `false`. ### Returns `Promise`: An object representing the output of the linter. ``` -------------------------------- ### runRuleset(ruleset, targets, fileSystem, dryRun) Source: https://todogroup.github.io/repolinter Executes all operations in a ruleset, including linting and fixing, and returns the results. ```APIDOC ## runRuleset(ruleset, targets, fileSystem, dryRun) ### Description Run all operations in a ruleset, including linting and fixing. Returns a list of objects with the output of the linter rules. ### Method runRuleset ### Parameters - **ruleset** (Array) - Required - A ruleset (list of rules with information about each). This parameter can be generated from a config using parseConfig. - **targets** ((Object | boolean)) - Required - The axiom targets to enable for this run of the ruleset. Structure is from the output of determineTargets. Use true for all targets. - **fileSystem** (FileSystem) - Required - A filesystem object configured with filter paths and a target directory. - **dryRun** (boolean) - Required - If true, repolinter will report suggested fixes, but will make no disk modifications. ### Returns `Promise>`: Objects indicating the result of the linter rules. ``` -------------------------------- ### Limit paths with --allowPaths Source: https://todogroup.github.io/repolinter Use the --allowPaths option to specify an allowed list of paths, preventing accidental linting of build artifacts. Paths must be contained in the target directory/repository. ```bash repolinter lint --allowPaths ./a/path --allowPaths /another/path ``` -------------------------------- ### Formatter Source: https://todogroup.github.io/repolinter Documentation for the Formatter object and its formatOutput property. ```APIDOC ## Formatter ### Description Object containing a function to format the entire linter output. ### Properties - **formatOutput** (function (LintResult, boolean): string) - A function to format the entire linter output. ``` -------------------------------- ### Minimal README existence rule (JSON and YAML) Source: https://todogroup.github.io/repolinter Minimal rule that checks for the existence of a README file using the file-existence check with globsAny set to README*. Shown in JSON and YAML. ```json "readme-file-exists" : { "level": "error", "rule": { "type": "file-existence", "options": { "globsAny": ["README*"] } } } ``` ```yaml readme-file-exists: level: error rule: type: file-existence options: globsAny: - README* ``` -------------------------------- ### Register Rule Configuration Schema in rulesets/schema.json Source: https://todogroup.github.io/repolinter Item to add to the `root.then.properties.rules.properties.rule.allOf` list in `rulesets/schema.json` to register the rule configuration schema. This is required due to limitations with JSON Schema. ```json { "if": { "properties": { "type": { "const": "" } } }, "then": { "properties": { "options": { "$ref": "../rules/-config.json" } } } } ``` -------------------------------- ### Lint a Local Repository with repolinter lint Source: https://todogroup.github.io/repolinter Lint a local repository directory with Repolinter. Uses the local repolinter.json ruleset or the default ruleset if none is found. ```bash repolinter lint ``` -------------------------------- ### Invoke repolinter with URL ruleset Source: https://todogroup.github.io/repolinter Invokes repolinter with a URL-based ruleset. Relative paths in `extends` are resolved relative to the original URL. ```bash repolinter -u http://example.com/custom-rules.yaml ``` -------------------------------- ### README hash check with fix (JSON and YAML) Source: https://todogroup.github.io/repolinter Rule that checks the README against a SHA256 hash and replaces it if the check fails. Uses the file-hash check and the file-create fix with replace: true and a text URL. Includes policyInfo and policyUrl. ```json "readme-file-up-to-date" : { "level": "error", "rule": { "type": "file-hash", "options": { "globsAny": ["README*"], "algorithm": "sha256", "hash": "..." } }, "fix": { "type": "file-create", "options": { "file": "README.md", "replace": true, "text": { "url": "www.example.com/mytext.txt" } } }, "policyInfo": "Gotta keep that readme up to date", "policyUrl": "www.example.com/mycompany" } ``` ```yaml readme-file-up-to-date: level: error rule: type: file-hash options: globsAny: - README* algorithm: sha256 hash: "..." fix: type: file-create options: file: README.md replace: true text: url: www.example.com/mytext.txt policyInfo: Gotta keep that readme up to date policyUrl: www.example.com/mycompany ``` -------------------------------- ### Invoke repolinter with file ruleset Source: https://todogroup.github.io/repolinter Invokes repolinter with a file-based ruleset. Relative paths in `extends` are resolved relative to the original file path. ```bash repolinter -r /etc/repolinter/custom-rules.yaml ``` -------------------------------- ### Axioms configuration syntax Source: https://todogroup.github.io/repolinter Defines the axioms configuration object in JSON and YAML formats. Each axiom is a key-value pair where the key is the axiom ID and the value is the target used in the `where` conditional. ```json "axioms": { "": "" } ``` ```yaml axioms: : axiom-target ``` -------------------------------- ### Rule Configuration JSON Schema Template Source: https://todogroup.github.io/repolinter Template for a rule configuration JSON schema. The file must be named `-config.json` and placed under the `rules` folder. The top-level type must be `object` and the `$id` field must be an absolute raw.githubusercontent.com URL to the hosted schema. ```json { "$schema": "http://json-schema.org/draft-07/schema", "$id": "https://raw.githubusercontent.com/todogroup/repolinter/master/rules/-config.json", "type": "object", "properties": {} } ``` -------------------------------- ### Lint a remote git repository with --git flag Source: https://todogroup.github.io/repolinter Use the --git flag to lint a remote repository. The directory input is interpreted as a git URL and Repolinter automatically clones it into a temporary directory. ```bash repolinter lint -g https://github.com/todogroup/repolinter.git ``` -------------------------------- ### Rule Implementation Interface Source: https://todogroup.github.io/repolinter Interface for a rule implementation module. `fs` is a `FileSystem` scoped to the current repository and `opts` is the options provided by the ruleset. Use `Result#targets` to show individual files/patterns checked; avoid filenames in `Result#message`. Throw an error if the rule fails to execute. ```typescript async (fs: FileSystem, opts /* type determined by your JSON schema */) => Result ``` -------------------------------- ### Extending a ruleset with extends Source: https://todogroup.github.io/repolinter Extends a ruleset by including an `extends` top-level key with a URL or file path. The two files are recursively merged, and extended rulesets can be up to 20 levels deep. ```json { "extends": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/default.json" "rules": { # disable CI check "integrates-with-ci": { "level": "off" } } } ``` ```yaml extends: https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/default.json rules: # disable CI check integrates-with-ci level: off ... ``` -------------------------------- ### determineTargets(axiomconfig, fs) Source: https://todogroup.github.io/repolinter Determines the appropriate targets to run against based on an axiom configuration. ```APIDOC ## determineTargets(axiomconfig, fs) ### Description Given an axiom configuration, determine the appropriate targets to run against (e.g. "target=javascript"). ### Method determineTargets ### Parameters - **axiomconfig** (type not specified) - Required - The axiom configuration. - **fs** (type not specified) - Required - The filesystem object. ### Returns Not specified in the source. ``` -------------------------------- ### Lint a repository with the Repolinter JavaScript API Source: https://todogroup.github.io/repolinter Use the Repolinter JavaScript API to lint a repository. The lint function returns a promise that resolves to a result object. This API gives developers complete control over configuration and formatting. ```javascript const repolinter = require('repolinter') const result = await repolinter.lint('.') ``` -------------------------------- ### Formatter interface Source: https://todogroup.github.io/repolinter Defines the contract for a Repolinter formatter. Implementations must return the formatted output as a string instead of printing to STDOUT. ```typescript interface Formatter { formatOutput(output: LintResult, dryRun: boolean): string } ``` -------------------------------- ### Axiom implementation interface Source: https://todogroup.github.io/repolinter Interface for an axiom implementation. The function receives a FileSystem scoped to the current repository and returns a Result. The result should contain an array of targets where t.path is a valid target. On failure, return a failing result with an error message instead of throwing. ```typescript async (fs: FileSystem) => Result ``` -------------------------------- ### Fix Schema Registration in rulesets/schema.json Source: https://todogroup.github.io/repolinter Register the fix schema in rulesets/schema.json by adding this item to the list under root.then.properties.rules.properties.fix.allOf. Note this is a different list than the rule registration list. ```json { "if": { "properties": { "type": { "const": "" } } }, "then": { "properties": { "options": { "$ref": "../rules/-config.json" } } } } ``` -------------------------------- ### Repolinter ruleset base (JSON and YAML) Source: https://todogroup.github.io/repolinter Base structure for a Repolinter ruleset in JSON and YAML. The JSON version includes the $schema field for validation; the YAML version omits it. Use version 2 unless you have a legacy configuration. ```json { "$schema": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/schema.json", "version": 2, "axioms": {}, "rules": {} } ``` ```yaml version: 2 axioms: {} rules: ``` -------------------------------- ### MarkdownFormatter and slug API Source: https://todogroup.github.io/repolinter Code snippets for the MarkdownFormatter class methods and the slug function. ```APIDOC ## MarkdownFormatter.formatResult(result, symbol, dryRun?) ### Description Formats a FormatResult object into a line of human-readable text. ### Method formatResult ### Signature formatResult(result: FormatResult, symbol: string, dryRun?: boolean): string ### Parameters - **result** (FormatResult) - Required - The result to format, must be valid. - **symbol** (string) - Required - The symbol to use at the start of the log line (ex. ✅). - **dryRun** (boolean?) - Optional - Whether or not to say the fix is "suggested" instead of "applied". ### Returns - **string** - The formatted string. ``` ```APIDOC ## MarkdownFormatter.formatOutput(output, dryRun?) ### Description Formats a LintResult object into a human-readable output. ### Method formatOutput ### Signature formatOutput(output: LintResult, dryRun?: boolean): string ### Parameters - **output** (LintResult) - Required - The linter output to format. - **dryRun** (boolean?) - Optional - Whether or not to print fix "suggested" or "applied". ### Returns - **string** - The formatted output. ``` ```APIDOC ## slug(string) ### Description Parses a unicode string into a markdown anchor link using a GitHub-flavored algorithm. ### Method slug ### Signature slug(string: string): string ### Parameters - **string** (string) - Required - The heading to parse. ### Returns - **string** - The slug to use in URLs. ``` -------------------------------- ### Fix Implementation Interface Source: https://todogroup.github.io/repolinter Interface for a fix implementation. The function receives a FileSystem scoped to the current repository, options from the ruleset, target filepaths that failed the associated rule, and a dryRun flag. It should return a Result, using Result#targets to show changed files, or throw an error on failure. ```typescript async (fs: FileSystem, options /* Type determined by your JSON schema */, targets: string[], dryRun: boolean) => Result ``` -------------------------------- ### shouldRuleRun(validTargets, ruleAxioms) Source: https://todogroup.github.io/repolinter Determines whether a rule should run based on its axioms and a list of valid targets. ```APIDOC ## shouldRuleRun(validTargets, ruleAxioms) ### Description Checks a rule's list of axioms against a list of valid targets, and determines if the rule should run or not based on the following rules criteria: the rule's list has a direct match on a target OR the rule specifies a numerical axiom (ex. >) and the target list contains a target that matches that axiom. Supported numerical axioms are >, <, >=, <=, and = Only. ### Method shouldRuleRun ### Parameters - **validTargets** (Array) - Required - The axiom target list in "target=thing" format, including the wildcard entry ("target=_"). For numerical targets it is assumed that only one entry and the wildcard are present (e.g. ["target=2", "target=3", "target=_ "] is invalid). - **ruleAxioms** (Array) - Required - The rule "where" specification to validate against. ### Returns `Array`: The list of unsatisfied axioms, if any. Empty array indicates the rule should run. ``` -------------------------------- ### Repolinter rule template (JSON and YAML) Source: https://todogroup.github.io/repolinter Template for a Repolinter rule in JSON and YAML. The rule object contains the check (rule), error level, optional where conditions, optional fix action, and optional policy information. The where array uses axiom conditions like condition=*. ```json "": { "level": "error" | "warning" | "off", "rule": { "type": "", "options": { // } }, "where": ["condition=*"], "fix": { "type": "", "options": { // } }, "policyInfo": "...", "policyUrl": "..." } ``` ```yaml : level: error | warning | off rule: type: options: where: [condition=*] fix: type: options: policyInfo: >- ... policyUrl: >- ... ``` -------------------------------- ### Disable automatic fixes with --dryRun Source: https://todogroup.github.io/repolinter Use the --dryRun flag to disable automatic execution of fixes specified by the ruleset. By default, Repolinter automatically executes fixes. ```bash repolinter lint --dryRun ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.