lsa-cli 1.0.0

CLI part of Linking Software Artifacts project

LSA (Linking Software Artifacts) CLI

The part of LSA project, this CLI tool is used to parse annotations from source code and convert them to entities. Entities are then used to visualize the codebase on the webpage.

Installation

pip install lsa-cli

Usage

lsa-cli <option>

Options:

-p, --path          Parse path
-a, --annotations  Save intermediate annotations model as JSON
-c, --config       Path to the configuration file
-v, --validate     Validate and compare two model files (JSON). Provide two file paths.

Example

The CLI tool parses the source code:

// @lc-entity
// @lc-identifier :Annotation
// @lc-name Annotation
// @lc-description Base class for all annotations.
export interface IAnnotation {
  // @lc-property
  // @lc-name name
  name: string
  // @lc-property
  // @lc-name value
  value: string | null
  // @lc-property
  // @lc-name annotationStartPos
  startPos: number
  // @lc-property
  // @lc-name annotationEndPos
  endPos: number
  // @lc-property
  // @lc-name annotationLine
  lineNumber: number
}

And generates the entities model by lsa-cli -p source-file.ts:

{
  "entities": [
    {
      "name": "Annotation",
      "instances": [
        {
          "from_file": "source-file.ts",
          "identifier": ":Annotation",
          "description": "Base class for all annotations.",
          "properties": [
            {
              "name": "name",
              "description": null
            },
            {
              "name": "value",
              "description": null
            },
            {
              "name": "annotationstartpos",
              "description": null
            },
            {
              "name": "annotationendpos",
              "description": null
            },
            {
              "name": "annotationline",
              "description": null
            }
          ]
        }
      ]
    }
  ]
}

Additionally, you can save the intermediate annotations model as JSON:

{
    "filesAnnotations": [
        {
            "relativeFilePath": "./source-file.ts",
            "annotations": [
                {
                    "name": "entity",
                    "value": null,
                    "lineNumber": 1
                },
                {
                    "name": "identifier",
                    "value": ":Annotation",
                    "lineNumber": 2
                },
                {
                    "name": "name",
                    "value": "Annotation",
                    "lineNumber": 3
                },
        ...

Configuration file

Default configuration file is .lsa-config.json in the current working directory. You can specify the path to the configuration file using the -c option.

lsa-cli -c <path-to-config-file> -p <path-to-source-code>

If the file is not found, default configuration is used:

{
  "markers": {
    "prefix": "@lc-",
    "identifier": "identifier",
    "name": "name",
    "type": "type",
    "description": "description",
    "entity": "entity",
    "property": "property",
    "method": "method",
    "source": "source"
  },
  "parser": {
    "output": {
      "entities": "entities.json",
      "annotations": "annotations.json"
    },
    "exclude": [],
    "extend": {}
  },
}

• <prefix><marker> - Defines the annotations, where
  • prefix - Prefix for the annotations.
  • markers - Annotation markers (for example, <prefix>entity).
• parser - Parser settings for the CLI.

  • output - Output files for the CLI.

  • exclude - Paths to exclude from parsing.

    "exclude": ["node_modules", ".git", ".venv"]
    

  • extend - File extensions to extend the parser. Where the key is the extension and the value is the MIME type ( you can see the list of supported MIME types here).

    "extend": {
      "cjs": "application/javascript",
      "mjs": "application/javascript",
      "jsx": "application/javascript"
    }
    

Development

Installation

poetry install

Usage

poetry run lsa-cli

Testing

pytest -c pyproject.toml

Formatting

poetry run poe format-code

Pre-commit

poetry shell
pre-commit install